gdb-mcp

An MCP server that lets an AI agent drive a full C/C++ debugging session — set breakpoints, step, inspect memory and variables, evaluate expressions, and call functions — using either GDB or LLDB behind one unified tool surface.

It works by speaking the Debug Adapter Protocol (DAP) to the debugger that ships with your toolchain (gdb -i dap or lldb-dap), so a single set of tools drives both debuggers.

Validated end-to-end with Claude Code, Codex CLI, and Cursor CLI — each agent independently used these tools to debug a live program and extract correct runtime state.

---

Features

• Three ways to start: launch a prebuilt binary, compile-then-debug a source file, or attach to a running process (by PID).
• Execution control: continue, step (over / into / out, line or instruction granularity), and a lock-free pause that can interrupt a running program.
• Breakpoints: source (file:line) and function breakpoints, with conditions, hit counts, and logpoints; data breakpoints (watchpoints); stable handles for reliable removal.
• Inspection: backtraces, threads, stack frames, scopes, lazy variable expansion (structs/arrays/STL), expression evaluation and function calls (foo(x)), set-variable, read-memory, and disassembly.
• Source listing around the current stop, plus a raw-command escape hatch (dbg_raw_command) for anything the structured tools don't cover.
• Agent-friendly output: verbose DAP payloads are trimmed to compact JSON, with stop-epoch guards so an agent can't accidentally read a stale frame or variable reference after the program advances.

Prerequisites

• Python 3.11+
• A DAP-capable debugger:
  • GDB ≥ 14 (ships the gdb -i dap interpreter), or
  • lldb-dap (bundled with LLVM / Xcode; on macOS it is found via xcrun -f lldb-dap).
• A C/C++ toolchain (cc/clang/gcc) for the compile-then-debug mode and to build debuggees with -g.
• uv (recommended) or pip.

Platform note. On Linux, run debuggers normally. On macOS, live debugging needs the debugserver attach permission — if dbg_start returns "Not allowed to attach", enable Developer Mode once: sudo DevToolsSecurity -enable. macOS arm64 GDB cannot debug native Mach-O binaries; use LLDB locally and GDB on Linux.

Installation

git clone https://github.com/birdeclipse/gdb-mcp.git
cd gdb-mcp
uv venv && uv pip install -e ".[dev]"   # or: pip install -e ".[dev]"

Verify the server starts and advertises its tools:

uv run gdb-mcp        # starts the MCP server on stdio (Ctrl-C to stop)
uv run pytest -m mcp  # asserts the server advertises all 20 tools

Registering with an agent

The server runs over stdio. The robust invocation lets uv resolve the project venv regardless of PATH (replace /path/to/gdb-mcp with your clone path):

command: uv
args:    ["run", "--directory", "/path/to/gdb-mcp", "gdb-mcp"]

Ready-to-edit config snippets live in integrations/. Summary:

Agent	How
Claude Code	claude mcp add gdb-mcp -- uv run --directory /path/to/gdb-mcp gdb-mcp — or merge integrations/mcp.claude.json into .mcp.json
Codex CLI	merge integrations/codex.config.toml into ~/.codex/config.toml
Cursor CLI	copy integrations/mcp.cursor.json to .cursor/mcp.json (project) or ~/.cursor/mcp.json

If you pip install the package so gdb-mcp is on PATH, you can use command: gdb-mcp with empty args instead.

Tools

All tools except dbg_start take a session_id.

Tool	Purpose
dbg_start	Start a session: mode = launch / compile_launch / attach, debugger = gdb / lldb
dbg_terminate	Kill (launch) or detach (attach) and free the session
dbg_continue	Resume until the next stop / exit
dbg_step	Step over / into / out; line or instruction granularity
dbg_pause	Interrupt a running program (lock-free)
dbg_set_breakpoint	file:line or function; optional condition, hit_condition, log_message
dbg_list_breakpoints	List source / function / data breakpoints with handles
dbg_remove_breakpoint	Remove by stable handle
dbg_set_watchpoint	Data breakpoint on a variable (read / write / rw)
dbg_backtrace	Stack frames for a thread
dbg_list_threads	All threads
dbg_select_frame	Set the active frame for eval / scopes / variables
dbg_scopes	Variable scopes (Locals, …) for a frame
dbg_variables	Expand a variablesReference (lazy struct/array/STL expansion)
dbg_evaluate	Evaluate an expression or call a function (foo(x))
dbg_set_variable	Set a variable to a new value
dbg_read_memory	Read raw memory (base64)
dbg_disassemble	Disassemble around an address
dbg_source	Source lines around a location
dbg_raw_command	Run a raw gdb/lldb command (escape hatch)

Example: a debugging session

A typical agent flow against a program with a Point pt = {3, 7} local:

1. dbg_start(mode="launch", debugger="lldb", program="/path/to/a.out") → stops at entry, returns a session_id.
2. dbg_set_breakpoint(session_id, file="main.c", line=6) → verified, handle 1.
3. dbg_continue(session_id) → {state: "stopped", reason: "breakpoint", frame: {function: "main", file: "main.c", line: 6}}.
4. dbg_backtrace(session_id) → frames.
5. dbg_scopes(session_id) → Locals; dbg_variables(session_id, ref=…) → pt (expandable) → expand → {x: 3, y: 7}.
6. dbg_evaluate(session_id, "pt.x + pt.y") → 10.
7. dbg_terminate(session_id).

How it works

agent ──MCP tool call──▶ MCP server (Python, asyncio)
                              │  Session Manager  (session_id → one debuggee)
                              │  DAP Client       (Content-Length framing,
                              │                    request/response + async events)
                              ▼  spawns
                    gdb -i dap   |   lldb-dap
                              ▼
                      debuggee process

Execution tools are event-driven: continue/step resolve on the debugger's next stopped/exited event, not on the request response. See docs/ARCHITECTURE.md for the design and CONTRIBUTING.md for development.

Testing

uv run pytest                # everything
uv run pytest tests/unit     # offline (scripted fake adapter) — no debugger
uv run pytest -m mcp         # MCP stdio handshake + tool advertisement
uv run pytest -m integration # live debugger on the C fixtures (auto-skips if none)

The integration suite probes for a working debugger and skips cleanly when none is available, so it is safe to run anywhere.

License

MIT