Skip to main content
Glama
William-An

cpp-debug-mcp

by William-An
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

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

Related MCP server: GDB MCP Server

Quick Start

Register the MCP server globally (all projects, auto-updates):

claude mcp add --scope user cpp-debug -- uvx cpp-debug-mcp

That'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-mcp

From GitHub

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 ".[dev]"

Register with Claude Code

Global (all projects)

claude mcp add --scope user cpp-debug -- uvx cpp-debug-mcp

Per-project (CLI)

claude mcp add cpp-debug -- uvx cpp-debug-mcp

Per-project (.mcp.json)

{
  "mcpServers": {
    "cpp-debug": {
      "type": "stdio",
      "command": "uvx",
      "args": ["cpp-debug-mcp"]
    }
  }
}

Scope

Flag

Config file

Availability

User

--scope user

~/.claude.json

All projects, private to you

Project

--scope project

.mcp.json

This project, shared via git

Local

(default)

.mcp.json

This project, private to you

Tools

GDB Tools (16)

Tool

Description

gdb_start_session

Start a GDB session for a compiled executable

gdb_end_session

End a session and clean up

gdb_run

Start execution (optionally stop at main)

gdb_set_breakpoint

Set a breakpoint by file:line, function, or address

gdb_delete_breakpoint

Delete a breakpoint by ID

gdb_list_breakpoints

List all active breakpoints

gdb_continue

Continue until next breakpoint or exit

gdb_step

Step into, over, or out of functions

gdb_backtrace

Get the call stack

gdb_list_variables

List local variables in a stack frame

gdb_evaluate

Evaluate a C++ expression (e.g. *ptr, arr[5])

gdb_read_memory

Read raw memory at an address

gdb_thread_info

List all threads and their states

gdb_raw_command

Execute a raw GDB command (with safety restrictions)

gdb_open_console

Open an interactive GDB console via tmux (requires tmux)

gdb_close_console

Close the interactive GDB console

LSP/clangd Tools (8)

Tool

Description

lsp_start_session

Start a clangd session for a project

lsp_end_session

End a clangd session

lsp_diagnostics

Get compile errors and warnings for a file

lsp_hover

Get type/documentation info at a position

lsp_goto_definition

Find where a symbol is defined

lsp_find_references

Find all references to a symbol

lsp_document_symbols

List all symbols in a file

lsp_signature_help

Get function signature help at a call site

Combined Tools (3)

Tool

Description

inspect_variable_with_type

GDB runtime value + clangd type info for a variable

diagnose_crash_site

Backtrace + local variables + LSP diagnostics at crash

analyze_function

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 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/
    ├── 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 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

Install Server
A
license - permissive license
-
quality - not tested
A
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
0dRelease cycle
2Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/William-An/cpp-debug-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server