clangd

This MCP server provides a set of clangd-backed tooling via the Model Context Protocol to help you navigate and understand large C++ codebases. It exposes capabilities like finding symbol definitions and references, retrieving type information and documentation, listing workspace symbols, discovering implementations, and inspecting diagnostics and call/type hierarchies. You can invoke these tools through Claude Code or your configured MCP client, letting you query, for example, where a symbol is defined, how a symbol is referenced across the project, or what diagnostics clangd reports for a given file. The server coordinates with clangd to perform the underlying code intelligence tasks and returns structured results that can be displayed in your editor or chat interface. To begin, ensure the server is available via your chosen npm/npx approach and that your project includes a compile_commands.json file for clangd to index.

Prerequisites:

• Node.js >= 18.0.0
• clangd installed on your system
• A C++ project with compile_commands.json (generated via CMake or GN and accessible to clangd)

Install and run (recommended):

1. Install the MCP server via npm/npx as shown in the readme:

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

# From source (if you want to build locally):
# git clone https://github.com/felipeerias/clangd-mcp-server.git
# cd clangd-mcp-server
# npm install && npm run build && npm link

2. Ensure your project exposes compile_commands.json (e.g., via CMake):

• CMake: cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON /path/to/source
• Then provide the path to compile_commands.json to clangd (via PROJECT_ROOT/COMPILE_COMMANDS_DIR as needed).

3. Start the MCP server using the configuration example (npx-based):

npx -y clangd-mcp-server

4. (Optional) Configure Claude Code or your MCP client to reference the clangd MCP server, for example by adding:

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

5. Validate that the server is reachable and that clangd can index your codebase (background indexing can be adjusted via CLANGD_ARGS in env as needed).

Tips and troubleshooting:

• Ensure compile_commands.json is present and accurate for your project; without it, clangd may have limited indexing.
• You can customize clangd behavior via environment variables, for example enabling background indexing or increasing result limits using CLANGD_ARGS, LOG_LEVEL, and CLANGD_LOG_LEVEL.
• If you use Claude Code, you can enable unrestricted tool usage with alwaysAllow: ["*"] but be mindful of granting broad access in shared environments.
• For large codebases, consider using remote indexing or tuning CLANGD_ARGS to optimize performance (e.g., --background-index, --limit-results=1000).
• If you run into path resolution issues, set PROJECT_ROOT to the absolute project root and ensure CLANGD_PATH points to a valid clangd binary when needed.
• The MCP server supports a range of clangd-based queries including find_definition, find_references, get_hover, workspace_symbol_search, find_implementations, get_document_symbols, get_diagnostics, get_call_hierarchy, and get_type_hierarchy.