Skip to main content
Glama
schuay

clangd-mcp

by schuay
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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

Related MCP server: fw-context-mcp

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)

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessResponsive

Resources

Related MCP Connectors

Related MCP Servers

  • Clangaroo

    jasondk
    A
    license
    Not graded
    quality
    D
    maintenance
    Provides fast C++ code intelligence for LLMs by combining Tree-sitter parsing with clangd LSP for efficient symbol lookup, navigation, and hierarchy analysis. It optionally integrates Google Gemini AI to deliver deeper architectural insights and automated documentation summaries.
    23
    MIT

  • fw-context-mcp

    turbyho
    A
    license
    A
    quality
    A
    maintenance
    Exposes tools for AI assistants to query a persistent SQLite+FTS5 index of C/C++ symbols parsed from real build commands, enabling sub-millisecond lookup, full-text search, and natural-language explanation without hallucination.
    39
    8
    MIT

  • clangd-mcp-server

    felipeerias
    A
    license
    A
    quality
    F
    maintenance
    Provides C++ code intelligence tools for AI agents via the Model Context Protocol, enabling symbol navigation, type information, and diagnostics.
    9
    44
    Mozilla Public 2.0

  • cpp-debug-mcp

    William-An
    A
    license
    A
    quality
    C
    maintenance
    Provides GDB and clangd-based tools for debugging C++ programs, enabling step execution, variable inspection, diagnostics, and combined runtime-static analysis.
    27
    1
    MIT