clangd-mcp

clangd-mcp

Experimental — expect rough edges and breaking changes.

A minimal Model Context Protocol server that bridges AI assistants to clangd for C/C++ code intelligence.

How it works

Claude / Gemini  ←─ MCP (stdio) ─→  server.py  ←─ LSP (stdio) ─→  clangd

server.py speaks MCP to the AI client and LSP (JSON-RPC 2.0 over stdin/stdout) to clangd. The two protocols are bridged by nine tools:

| Tool | LSP call(s) | Description | |---|---|---| | find_symbol | workspace/symbol | Search symbols by name (fuzzy) | | get_definition | workspace/symbol → textDocument/definition | Show the definition site with source | | find_references | workspace/symbol → textDocument/references | List every usage, grouped by file | | get_type_info | workspace/symbol → textDocument/hover | Show type signature and doc comment | | find_implementations | workspace/symbol → textDocument/implementation | Find concrete implementations of a virtual method or interface | | get_callers | workspace/symbol → prepareCallHierarchy → incomingCalls | Find every call site that calls a function | | get_callees | workspace/symbol → prepareCallHierarchy → outgoingCalls | Find every function called by a function | | list_file_symbols | textDocument/documentSymbol | List all symbols defined in a file | | get_type_hierarchy | workspace/symbol → prepareTypeHierarchy → supertypes + subtypes | Show base classes and derived classes |

Requirements

• Python ≥ 3.12
• uv
• clangd on $PATH (or specify --clangd)
• A compile_commands.json for your project (CMake: cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON)

Installation

uv tool install git+https://github.com/schuay/clangd-mcp.git

This installs a clangd-mcp command into an isolated environment and puts a shim on your $PATH. Upgrade later with:

uv tool upgrade clangd-mcp

Gemini CLI

curl -fsSL https://raw.githubusercontent.com/schuay/clangd-mcp/main/install-gemini.sh | bash

This installs the tool, prompts for project paths, and adds the server to ~/.gemini/settings.json. Requires jq.

Or add manually to ~/.gemini/settings.json:

{
  "mcpServers": {
    "clangd": {
      "command": "clangd-mcp",
      "args": [
        "--compile-commands-dir", "/path/to/your/build",
        "--workspace-dir", "/path/to/your/project",
        "--seed-file", "/path/to/your/project/src/main.cpp"
      ]
    }
  }
}

Options

All flags are optional:

| Flag | Default | Description | |---|---|---| | --clangd | clangd | Path to the clangd binary | | --compile-commands-dir | (none) | Directory containing compile_commands.json | | --workspace-dir | current directory | Root of the C/C++ project | | --seed-file | (none) | Source file to open at startup to trigger background indexing | | --log-level | WARNING | DEBUG / INFO / WARNING / ERROR (to stderr) |

Tests

uv run python tests.py
# or with pytest for coloured output:
uv run pytest tests.py -v

The test suite runs without a real clangd binary — it drives the LSP client with canned in-process responses and patches the global lsp object when testing the MCP tool handlers.

File structure

server.py        MCP server: tools, arg parsing, clangd lifecycle
lsp_client.py  LSP client: subprocess management, JSON-RPC framing, queries
tests.py       Unit tests (no clangd required)
pyproject.toml Dependencies (mcp>=1.0)