cpp-debug-mcp
Provides tools for debugging C++ programs using the GNU Debugger (GDB), including session management, breakpoints, stepping, backtrace, variable inspection, and expression evaluation.
Provides tools for static analysis of C++ code using clangd (part of the LLVM project), including diagnostics, hover information, go-to-definition, references, and document symbols.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@cpp-debug-mcp debug segfault in my program and show backtrace"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Related MCP server: lldb-mcp-server
Quick Start
Register the MCP server globally (all projects, auto-updates):
claude mcp add --scope user cpp-debug -- uvx cpp-debug-mcpThat's it. Verify with /mcp inside Claude Code to confirm the server is connected.
Installation Options
Auto-updating via uvx (recommended)
No install step needed — uvx fetches the latest version from PyPI on each invocation. Just register with the command above.
From PyPI
pip install cpp-debug-mcpFrom GitHub
pip install git+https://github.com/William-An/cpp-debug-mcp.gitFrom 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 ".[dev]"Register with Claude Code
Global (all projects)
claude mcp add --scope user cpp-debug -- uvx cpp-debug-mcpPer-project (CLI)
claude mcp add cpp-debug -- uvx cpp-debug-mcpPer-project (.mcp.json)
{
"mcpServers": {
"cpp-debug": {
"type": "stdio",
"command": "uvx",
"args": ["cpp-debug-mcp"]
}
}
}Scope | Flag | Config file | Availability |
User |
|
| All projects, private to you |
Project |
|
| This project, shared via git |
Local | (default) |
| This project, private to you |
Tools
GDB Tools (16)
Tool | Description |
| Start a GDB session for a compiled executable |
| End a session and clean up |
| Start execution (optionally stop at |
| Set a breakpoint by file:line, function, or address |
| Delete a breakpoint by ID |
| List all active breakpoints |
| Continue until next breakpoint or exit |
| Step into, over, or out of functions |
| Get the call stack |
| List local variables in a stack frame |
| Evaluate a C++ expression (e.g. |
| Read raw memory at an address |
| List all threads and their states |
| Execute a raw GDB command (with safety restrictions) |
| Open an interactive GDB console via tmux (requires tmux) |
| Close the interactive GDB console |
LSP/clangd Tools (8)
Tool | Description |
| Start a clangd session for a project |
| End a clangd session |
| Get compile errors and warnings for a file |
| Get type/documentation info at a position |
| Find where a symbol is defined |
| Find all references to a symbol |
| List all symbols in a file |
| Get function signature help at a call site |
Combined Tools (3)
Tool | Description |
| GDB runtime value + clangd type info for a variable |
| Backtrace + local variables + LSP diagnostics at crash |
| Breakpoint + signature + references + locals for a function |
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 infoArchitecture
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/
├── fmt.py # Human-readable output formatting
├── gdb_tools.py # 16 GDB MCP tools (incl. interactive console)
├── lsp_tools.py # 8 LSP MCP tools
└── combined_tools.py # 3 combined analysis toolsSafety
Command sanitization:
gdb_raw_commandblocksshell,!,python,pipe, andsourcecommandsResource 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/ -vGDB tests require gdb to be installed. LSP tests require clangd. Tests that need unavailable tools are automatically skipped.
License
MIT
Available Tools
27 toolsanalyze_functionA
Analyze a function using both GDB and LSP.
Sets a temporary breakpoint at the function, gets its signature and references from clangd, and retrieves local variables if the program is stopped there.
Inputs: gdb_session_id (required), lsp_session_id (required), function_name (required). Returns: result
diagnose_crash_siteA
Diagnose a crash by combining GDB backtrace with LSP static analysis.
When the program has stopped (e.g., SIGSEGV), this tool gathers:
Full backtrace from GDB
Local variables at the crash frame
Type information at each frame from clangd
Static diagnostics (warnings/errors) for relevant source files
Inputs: gdb_session_id (required), lsp_session_id (required), max_frames. Returns: result
gdb_backtraceB
Get the current call stack (backtrace).
Inputs: session_id (required), max_frames. Returns: result
gdb_close_consoleA
Close the interactive GDB console for a session.
Inputs: session_id (required). Returns: result
gdb_continueA
Continue program execution until next breakpoint or exit.
Inputs: session_id (required). Returns: result
gdb_delete_breakpointC
Delete a breakpoint.
Inputs: session_id (required), breakpoint_id (required). Returns: result
gdb_end_sessionA
End a GDB debugging session and clean up resources.
Inputs: session_id (required). Returns: result
gdb_evaluateB
Evaluate a C++ expression in the current debugging context.
Inputs: session_id (required), expression (required). Returns: result
gdb_list_breakpointsA
List all breakpoints in the session.
Inputs: session_id (required). Returns: result
gdb_list_variablesB
List local variables in a stack frame.
Inputs: session_id (required), frame. Returns: result
gdb_open_consoleA
Open an interactive GDB console so the programmer can step through code themselves.
Creates a tmux session with a full GDB console attached to the same debug session. Both Claude (via MCP tools) and the programmer (via the console) can control GDB simultaneously.
Requires tmux to be installed.
Inputs: session_id (required). Returns: result
gdb_raw_commandA
Execute a raw GDB command (with safety restrictions).
Blocked commands: shell, python, pipe, source.
Inputs: session_id (required), command (required). Returns: result
gdb_read_memoryC
Read raw memory at an address.
Inputs: session_id (required), address (required), count. Returns: result
gdb_runB
Start program execution in GDB.
Inputs: session_id (required), stop_at_main. Returns: result
gdb_set_breakpointB
Set a breakpoint at a location.
Inputs: session_id (required), location (required), condition. Returns: result
gdb_start_sessionC
Start a GDB debugging session for a compiled C++ executable.
Inputs: executable (required), args, working_dir. Returns: result
gdb_stepB
Step through program execution.
Inputs: session_id (required), mode. Returns: result
gdb_thread_infoB
List all threads and their states.
Inputs: session_id (required). Returns: result
inspect_variable_with_typeA
Inspect a variable combining GDB runtime value with LSP type information.
Gets the variable's current value from GDB and its type/documentation from clangd for a complete picture.
Inputs: gdb_session_id (required), lsp_session_id (required), variable_name (required), file_path (required), +1 more. Returns: result
lsp_diagnosticsB
Get compile errors and warnings for a C++ file from clangd.
Inputs: session_id (required), file_path (required). Returns: result
lsp_document_symbolsB
List all symbols (functions, classes, variables) in a file.
Inputs: session_id (required), file_path (required). Returns: result
lsp_end_sessionB
End a clangd LSP session.
Inputs: session_id (required). Returns: result
lsp_find_referencesB
Find all references to a symbol.
Inputs: session_id (required), file_path (required), line (required), column (required). Returns: result
lsp_goto_definitionB
Find where a symbol is defined.
Inputs: session_id (required), file_path (required), line (required), column (required). Returns: result
lsp_hoverB
Get type and documentation info at a specific code position.
Inputs: session_id (required), file_path (required), line (required), column (required). Returns: result
lsp_signature_helpB
Get function signature help at a call site.
Inputs: session_id (required), file_path (required), line (required), column (required). Returns: result
lsp_start_sessionB
Start a clangd LSP session for static analysis of C++ code.
Inputs: project_root (required), compile_commands_dir. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 27 tools
Each tool has a clearly distinct purpose, with GDB and LSP tools separated by prefix, and combined tools like analyze_function and diagnose_crash_site uniquely bridging the two domains. No two tools are ambiguous in their function.
All tools follow a consistent naming pattern: gdb_ for GDB operations, lsp_ for LSP operations, and descriptive names for combined tools. The pattern is predictable and aids agent understanding.
27 tools is on the higher side, but the server covers two distinct domains (runtime debugging and static analysis), each with a reasonable set of operations. The count is justified by the comprehensive scope, though a slight reduction could improve focus.
The tool surface covers the full debugging lifecycle (session management, breakpoints, stepping, memory inspection, backtraces) and comprehensive LSP features (diagnostics, navigation, signature help). Minor missing features like watchpoints or program restart are present via raw commands, so no critical gaps.
Maintenance
Related MCP Connectors
C++ engineering review, delivered per API call as an atom service on Conduit Atoms.
Compile code with thousands of compilers, inspect the assembly, and share godbolt.org links
Diff gatekeeper, pre-merge review, unicode safety, SMT prover, dependency advisor.
AI-powered codebase analysis — call graphs, security, dead code, complexity. 150+ tools.
Related MCP Servers
- AlicenseAqualityDmaintenanceProvides structured debugging capabilities through LLDB, enabling AI assistants to set breakpoints, inspect variables, analyze crashes, disassemble code, and evaluate expressions in C/C++ programs.173Apache 2.0
- AlicenseNot gradedqualityDmaintenanceAn MCP server that exposes LLDB debugging capabilities, enabling AI-assisted interactive debugging of C/C++ applications through 40 specialized tools.22 PyPI4MIT
- AlicenseAqualityDmaintenanceProvides C++ code intelligence tools for AI agents via the Model Context Protocol, enabling symbol navigation, type information, and diagnostics.950Mozilla Public 2.0
- AlicenseNot gradedqualityDmaintenanceAttaches to a running C++ process and exposes tools to inspect live memory via a resident GDB subprocess, enabling LLMs to read fields, follow pointers, and access STL containers without modifying target code.MIT