Skip to main content
Glama
cpp-debug-mcp

cpp-debug-mcp

by William-An

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: lldb-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

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

Available Tools

27 tools
analyze_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

    A3.6/5.0

    Scored across 27 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Provides structured debugging capabilities through LLDB, enabling AI assistants to set breakpoints, inspect variables, analyze crashes, disassemble code, and evaluate expressions in C/C++ programs.
      17
      3
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that exposes LLDB debugging capabilities, enabling AI-assisted interactive debugging of C/C++ applications through 40 specialized tools.
      22 PyPI
      4
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Provides C++ code intelligence tools for AI agents via the Model Context Protocol, enabling symbol navigation, type information, and diagnostics.
      9
      50
      Mozilla Public 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Attaches 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