cpp-debug-mcp

A Claude Code MCP server plugin for C++ debugging. Integrates GDB (via GDB/MI) and clangd (via LSP) to give Claude Code tools for stepping through code, inspecting variables, reading diagnostics, and correlating runtime state with static analysis — all from the conversation.

Prerequisites

• Python 3.10+
• GDB (for debugging tools)
• clangd (for static analysis tools)
• uv (recommended) or pip

Installation

From PyPI (once published):

pip install cpp-debug-mcp

From GitHub (always available):

pip install git+https://github.com/William-An/cpp-debug-mcp.git

From source (for development):

git clone https://github.com/William-An/cpp-debug-mcp.git
cd cpp-debug-mcp
uv venv .venv
source .venv/bin/activate
uv pip install -e .

Register with Claude Code

Option A — CLI command:

claude mcp add cpp-debug -- python3 -m cpp_debug_mcp

Option B — add to your project's .mcp.json:

{
  "mcpServers": {
    "cpp-debug": {
      "type": "stdio",
      "command": "python3",
      "args": ["-m", "cpp_debug_mcp"],
      "env": {
        "GDB_PATH": "gdb",
        "CLANGD_PATH": "clangd"
      }
    }
  }
}

Verify with /mcp inside Claude Code to confirm the server is connected.

Tools

GDB Tools (14)

LSP/clangd Tools (8)

Combined Tools (3)

Example Usage

Compile your C++ program with debug symbols, then ask Claude Code to debug it:

> Compile main.cpp with debug symbols and find why it segfaults

Claude will:
1. Run g++ -g -O0 -o main main.cpp
2. Call gdb_start_session with the executable
3. Call gdb_run to execute until the crash
4. Call diagnose_crash_site to get the full crash report
5. Explain the root cause with backtrace, variable values, and type info

Architecture

src/cpp_debug_mcp/
├── server.py              # FastMCP entry point with lifespan management
├── gdb/
│   ├── controller.py      # Async GDB/MI subprocess wrapper (pygdbmi)
│   └── session.py         # Session lifecycle (max 4, 30min timeout)
├── lsp/
│   ├── client.py          # Async JSON-RPC client for clangd over STDIO
│   ├── protocol.py        # LSP message helpers and response parsers
│   └── session.py         # Session lifecycle (max 2, 30min timeout)
├── analysis/
│   └── correlator.py      # Cross-references GDB runtime + LSP static info
└── tools/
    ├── gdb_tools.py       # 14 GDB MCP tools
    ├── lsp_tools.py       # 8 LSP MCP tools
    └── combined_tools.py  # 3 combined analysis tools

Safety

• Command sanitization: gdb_raw_command blocks shell, !, python, pipe, and source commands
• Resource limits: Max 4 GDB sessions and 2 LSP sessions concurrently
• Auto-cleanup: Stale sessions are cleaned up after 30 minutes of inactivity
• Process lifecycle: All subprocesses are terminated on server shutdown

Running Tests

source .venv/bin/activate
uv pip install -e ".[dev]"
python -m pytest tests/ -v

GDB tests require gdb to be installed. LSP tests require clangd. Tests that need unavailable tools are automatically skipped.

License

MIT