Clangd MCP Server

Model Context Protocol server for clangd on large C++ codebases.

This MCP provides coding agents like Claude Code with a collection of tools that they may use to answer natural language queries from the user:

• find_definition: Jump to symbol definitions
  • "Find the definition at src/foo.cpp:42:10"
• find_references: Find all references to a symbol
  • "Find all references to the function at bar.h:100"
• get_hover: Get type information and documentation
  • "What's the type at baz.cpp:200:15?"
• workspace_symbol_search: Search symbols across workspace
  • "Find symbols matching 'HttpRequest'"
• find_implementations: Find interface/virtual method implementations
  • "Find implementations of interface.h:50"
• get_document_symbols: Get hierarchical symbol tree for a file
  • "Show all symbols in main.cpp"
• get_diagnostics: Get compiler errors, warnings, and notes
  • "Show errors in src/foo.cpp"
• get_call_hierarchy: Get function callers and callees
  • "Show callers/callees at main.cpp:100:5"
• get_type_hierarchy: Get base classes and derived classes
  • "Show base/derived classes at foo.h:42"

Requirements

• Node.js >= 18.0.0
• clangd
• A C++ project with compile_commands.json

Installation

# From npm (eventually!)
# npm install -g clangd-mcp-server

# From source
git clone https://github.com/felipeerias/clangd-mcp-server.git
cd clangd-mcp-server
npm install && npm run build && npm link

Configuration

Generating compile_commands.json

CMake: cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON /path/to/source

GN (Chromium): gn gen out/Default

gn gen --export-compile-commands out/default
ln -sf out/Default/compile_commands.json .
claude mcp add clangd-mcp-server clangd-mcp-server

Other: Check your project's documentation.

Claude Code Configuration

claude mcp add clangd-mcp-server clangd-mcp-server

Or add manually to ~/.claude.json or .claude.json:

{
  "mcpServers": {
    "clangd": {
      "command": "clangd-mcp-server",
      "env": {"PROJECT_ROOT": "/path/to/your/project"},
      "alwaysAllow": ["*"]
    }
  }
}

The alwaysAllow: ["*"] field allows all tools to run without prompting for user approval.

Project-Specific Configuration (CLAUDE.md)

To help Claude Code automatically use clangd MCP tools for your C++ project, add to your project's CLAUDE.md:

## C++ Code Navigation

This project uses the clangd MCP server for C++ code intelligence. Use these tools for:
- Finding definitions and references
- Getting type information
- Searching symbols
- Finding implementations
- Getting diagnostics

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | PROJECT_ROOT | Project workspace root | Current directory | | COMPILE_COMMANDS_DIR | Path to compile_commands.json directory | Auto-detected | | CLANGD_PATH | Path to clangd binary | Auto-detected | | CLANGD_ARGS | Additional clangd arguments | Auto-configured | | LOG_LEVEL | MCP log level (ERROR/WARN/INFO/DEBUG) | INFO | | CLANGD_LOG_LEVEL | Clangd log level | error |

Clangd auto-detection order: CLANGD_PATH → project bundled (Chromium: third_party/llvm-build/.../clangd) → system PATH

Some large projects bundle their own clangd.

Chromium is auto-detected at third_party/llvm-build/Release+Asserts/bin/clangd.

For other projects in a similar situation, set CLANGD_PATH to specify the bundled clangd.

For bettern performance, background indexing is disabled by default. Usually there is already an axisting clangd server taking care of indexing the codebase. You can enable it with:

{"env": {"CLANGD_ARGS": "--background-index --limit-results=1000"}}

Large projects might consider using remote index.

Verbose logging may be enabled with:

{"env": {"LOG_LEVEL": "DEBUG", "CLANGD_LOG_LEVEL": "verbose"}}

Examples:

// Chromium (auto-detects bundled clangd)
{"mcpServers": {"clangd": {"command": "clangd-mcp-server",
  "env": {"PROJECT_ROOT": "/home/user/chromium/src"},
  "alwaysAllow": ["*"]}}}

// Custom clangd binary
{"mcpServers": {"clangd": {"command": "clangd-mcp-server",
  "env": {"CLANGD_PATH": "/custom/path/clangd"},
  "alwaysAllow": ["*"]}}}

// Custom args (e.g., enable background indexing)
{"mcpServers": {"clangd": {"command": "clangd-mcp-server",
  "env": {"CLANGD_ARGS": "--background-index --limit-results=1000"},
  "alwaysAllow": ["*"]}}}

Architecture

Claude Code
    ↓ MCP (stdio)
clangd-mcp-server
    ├── ClangdManager (lifecycle, health monitoring)
    ├── LSPClient (JSON-RPC over stdio)
    ├── FileTracker (didOpen/didClose)
    └── Tools (find_definition, find_references, etc.)
        ↓ LSP requests
    clangd subprocess

Development

npm install        # Install
npm run build      # Build
npm run watch      # Watch mode
npm test           # Run tests
node dist/index.js # Test locally

License

MPL-2.0 - See LICENSE

References

Model Context Protocol • clangd • LSP