clangd-mcp

Containerized MCP server: a thin interface from agents to clangd. The image ships clangd, clangd-indexer, and clangd-index-server (the same remote-index stack as clangd-index.llvm.org).

Use it to build a static index, optionally host that index over gRPC, and serve clangd queries over MCP — either from a local --index-file or from a remote server (ours or LLVM's).

v1 keeps host paths as-is: bind-mount the workspace at the same absolute path inside the container.

This package does not implement review or diff workflows. Those belong in the caller.

Commands

clangd-mcp serve --workspace <dir> --index-file <file>
clangd-mcp serve --workspace <dir> --remote-index <host:port>
clangd-mcp index --compile-commands <file> --output <file>
clangd-mcp host  --index-file <file> --project-root <dir> [--port 50051]

serve requires exactly one of --index-file or --remote-index. --mount-point defaults to --workspace. Remote-index is passed to clangd as --remote-index-address and --project-root (GitHub clangd builds). Index build and hosting are container commands, not MCP tools.

Related MCP server: clangd-mcp-server

Docker

docker build -t clangd-mcp .

# Build an index (same absolute paths as the host).
docker run --rm \
  -v /home/me/proj:/home/me/proj \
  clangd-mcp index \
    --compile-commands /home/me/proj/build/compile_commands.json \
    --output /home/me/proj/.clangd-mcp/index.idx

# Optional: share that index over gRPC.
docker run --rm -p 50051:50051 \
  -v /home/me/proj:/home/me/proj \
  clangd-mcp host \
    --index-file /home/me/proj/.clangd-mcp/index.idx \
    --project-root /home/me/proj

# MCP over stdio (local file).
docker run -i --rm \
  -v /home/me/proj:/home/me/proj \
  clangd-mcp serve \
    --workspace /home/me/proj \
    --index-file /home/me/proj/.clangd-mcp/index.idx

# Or attach clangd to LLVM's public remote index.
docker run -i --rm \
  -v /home/me/llvm:/home/me/llvm \
  clangd-mcp serve \
    --workspace /home/me/llvm \
    --remote-index clangd-index.llvm.org:5900

Cursor / Claude Code (stdio):

{
  "mcpServers": {
    "clangd": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/home/me/proj:/home/me/proj",
        "clangd-mcp", "serve",
        "--workspace", "/home/me/proj",
        "--index-file", "/home/me/proj/.clangd-mcp/index.idx"
      ]
    }
  }
}

Without Docker, npm run build && node dist/src/main.js serve ... if clangd is on PATH.

MCP tools

search_symbols, get_symbol_info, get_hover, get_definition, get_declaration, get_type_definition, find_references, find_implementations, get_callers, get_callees, get_type_hierarchy, get_file_symbols, get_diagnostics, switch_source_header, get_ast, clangd_status.

Paths in tool arguments are absolute workspace paths (the same paths stored in the index). Positions are 0-based UTF-8.

CI

GitHub Actions (.github/workflows/ci.yml) runs unit tests, builds the image, indexes test/fixture inside that image, then drives every MCP tool over docker run -i … serve. A second pass hosts the index with clangd-index-server and repeats the tool checks through --remote-index.

See PLAN.md for the design.