Content
# Clangd MCP Server
[Model Context Protocol](https://modelcontextprotocol.io) 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
```bash
# 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`:
```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`:
```markdown
## 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:
```json
{"env": {"CLANGD_ARGS": "--background-index --limit-results=1000"}}
```
Large projects might consider using [remote index](https://clangd.llvm.org/design/remote-index).
Verbose logging may be enabled with:
```json
{"env": {"LOG_LEVEL": "DEBUG", "CLANGD_LOG_LEVEL": "verbose"}}
```
**Examples:**
```js
// 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
```bash
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](LICENSE)
## References
[Model Context Protocol](https://modelcontextprotocol.io) • [clangd](https://clangd.llvm.org) • [LSP](https://microsoft.github.io/language-server-protocol/)
