gdb-mcp
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., "@gdb-mcp set a breakpoint at main.c:10 and continue"
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.
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-freepausethat 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.
Related MCP server: MCP Debugger
Prerequisites
Python 3.11+
A DAP-capable debugger:
GDB ≥ 14 (ships the
gdb -i dapinterpreter), orlldb-dap(bundled with LLVM / Xcode; on macOS it is found viaxcrun -f lldb-dap).
A C/C++ toolchain (
cc/clang/gcc) for the compile-then-debug mode and to build debuggees with-g.uv(recommended) orpip.
Platform note. On Linux, run debuggers normally. On macOS, live debugging needs the debugserver attach permission — if
dbg_startreturns "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 toolsRegistering 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 |
|
Codex CLI | merge |
Cursor CLI | copy |
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 |
| Start a session: |
| Kill (launch) or detach (attach) and free the session |
| Resume until the next stop / exit |
| Step |
| Interrupt a running program (lock-free) |
|
|
| List source / function / data breakpoints with handles |
| Remove by stable |
| Data breakpoint on a variable ( |
| Stack frames for a thread |
| All threads |
| Set the active frame for eval / scopes / variables |
| Variable scopes (Locals, …) for a frame |
| Expand a |
| Evaluate an expression or call a function ( |
| Set a variable to a new value |
| Read raw memory (base64) |
| Disassemble around an address |
| Source lines around a location |
| 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:
dbg_start(mode="launch", debugger="lldb", program="/path/to/a.out")→ stops at entry, returns asession_id.dbg_set_breakpoint(session_id, file="main.c", line=6)→ verified, handle1.dbg_continue(session_id)→{state: "stopped", reason: "breakpoint", frame: {function: "main", file: "main.c", line: 6}}.dbg_backtrace(session_id)→ frames.dbg_scopes(session_id)→ Locals;dbg_variables(session_id, ref=…)→pt(expandable) → expand →{x: 3, y: 7}.dbg_evaluate(session_id, "pt.x + pt.y")→10.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 processExecution 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
Available Tools
20 toolsdbg_backtraceA
Return up to levels stack frames for a thread (default current thread).
Inputs: session_id (required), thread_id, levels.
dbg_continueC
Resume execution until the next stop, exit, or timeout.
Inputs: session_id (required).
dbg_disassembleC
Disassemble around a memory reference.
Inputs: session_id (required), memory_reference (required), instruction_count.
dbg_evaluateB
Evaluate an expression in a frame. Handles reads AND function calls (e.g. 'square(v)' or 'call square(v)'). context: watch|repl|hover.
Inputs: session_id (required), expression (required), frame_id, context.
dbg_list_breakpointsA
List all breakpoints tracked in this session, with their stable handles.
Inputs: session_id (required).
dbg_list_threadsC
List all threads of the debuggee.
Inputs: session_id (required).
dbg_pauseA
Interrupt a running program.
This only acknowledges the pause request; it does NOT wait for the stop.
A continue/step in flight holds the session lock for its whole await-for-stop,
so pause must run lock-free to interrupt it. The resulting stopped event is
delivered to that in-flight call's waiter, which returns the stop snapshot to
its own caller. The caller of dbg_pause receives only this ack.
Residual race (acceptable): pause may transiently reject at the exact instant a continue/step starts, while state is still STOPPED for the microsecond before run_and_wait flips it to RUNNING under the lock. Flipping to RUNNING early (before awaiting the resume response) minimizes this window.
Inputs: session_id (required).
dbg_raw_commandA
Run a raw gdb/lldb command via the DAP evaluate repl context. Use for the long tail no structured tool covers (e.g. 'info registers').
Inputs: session_id (required), command (required).
dbg_read_memoryB
Read count bytes of memory (base64) from a memory reference.
Inputs: session_id (required), memory_reference (required), count (required), offset.
dbg_remove_breakpointB
Remove a breakpoint by its stable session handle and resync the affected list.
Inputs: session_id (required), handle (required).
dbg_scopesC
List variable scopes (Locals, Registers, ...) for a frame.
Inputs: session_id (required), frame_id.
dbg_select_frameC
Set the active frame for evaluate/scopes/variables.
Inputs: session_id (required), frame_id (required).
dbg_set_breakpointA
Set a breakpoint at file:line OR on a function. Optional condition / hit count / logpoint.
Inputs: session_id (required), file, line, function, +3 more.
dbg_set_variableC
Set a variable (by container ref + name) to a new value.
Inputs: session_id (required), ref (required), name (required), value (required).
dbg_set_watchpointB
Set a data breakpoint (watchpoint) on a variable. access: read|write|rw.
Inputs: session_id (required), name (required), access.
dbg_sourceB
Return source lines around file:line (defaults to the current stop frame).
Inputs: session_id (required), file, line, context.
dbg_startC
Start a debug session. mode: launch|compile_launch|attach. debugger: gdb|lldb.
Inputs: mode (required), debugger (required), program, source, +5 more.
dbg_stepB
Step the current thread. kind: over|into|out. granularity: line|instruction.
Inputs: session_id (required), kind, granularity.
dbg_terminateC
Kill (launch) or detach (attach) and free the session.
Inputs: session_id (required).
dbg_variablesC
List variables under a variablesReference (from scopes or an expandable var).
Inputs: session_id (required), ref (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Each tool has a clearly distinct purpose. For example, dbg_continue and dbg_step both resume execution but differ explicitly in granularity, and dbg_evaluate vs dbg_raw_command cover expression evaluation and raw commands respectively, leaving no ambiguity.
All tools follow the 'dbg_' prefix followed by a verb_noun pattern (e.g., dbg_set_breakpoint, dbg_list_threads, dbg_source). The naming is uniform and predictable.
20 tools is well-scoped for a debugger MCP server. It covers essential operations without being overwhelming, and each tool earns its place in the set.
The tool surface covers all core debugger actions: session start/terminate, breakpoints, stepping, continue, pause, variable inspection, memory, disassembly, source, threads, and backtrace. There are no obvious gaps for standard debugging workflows.
Related MCP Connectors
Shared debugging memory for AI coding agents
Agent Replay Debugger MCP — record every agent step + deterministic replay. Step-debugger for
Live browser debugging for AI assistants — DOM, console, network via MCP.
Build, run, debug, test and ship Chrome, Firefox, Edge and Safari extensions from your AI agent.
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
- AlicenseAqualityAmaintenanceEnables AI agents to perform step-through debugging of Python, JavaScript/Node.js, and Rust programs using the Debug Adapter Protocol, with support for breakpoints, variable inspection, and stack traces.29194MIT
- AlicenseNot gradedqualityDmaintenanceA GDB debugging tool designed for AI Agents (Claude Code, etc.)40Apache 2.0
- FlicenseAqualityDmaintenanceEnables AI agents to debug embedded systems by providing a comprehensive interface for GDB operations across multiple architectures like ARM and x86. It supports remote debugging via gdbserver or QEMU, allowing for detailed inspection of memory, registers, stack frames, and variables.31-