README.md
MCP server that exposes GDB debugging as tools.
gdb-mcp
MCP server that exposes GDB debugging as tools. An AI assistant can set breakpoints, run programs, step through code, inspect variables and memory, and examine registers — all via structured tool calls.
Reverse debugging with rr is also supported.
Requirements
- Python 3.12+
- uv
- GDB on
$PATH - rr on
$PATH(optional — only needed forrr_record/start_replay_session)
Installation
uv tool install git+https://github.com/schuay/gdb-mcp.git
This installs a gdb-mcp command into an isolated environment and puts a
shim on your $PATH. Upgrade later with:
uv tool upgrade gdb-mcp
Install and configure Gemini CLI
curl -fsSL https://raw.githubusercontent.com/schuay/gdb-mcp/main/install-gemini.sh | bash
This installs the tool and adds the server to ~/.gemini/settings.json.
Requires jq.
Tools
Session management
| Tool | Description |
|---|---|
start_session |
Spawn a GDB process, optionally loading a binary |
stop_session |
Kill a session and free its resources |
list_sessions |
Show all active sessions with idle time and kind (gdb / rr-replay) |
Time-travel debugging (rr)
rr records a full execution trace and replays it deterministically, enabling reverse-execution (reverse-continue, reverse-step, etc.).
| Tool | Description |
|---|---|
rr_record |
Record a program execution; returns trace_dir for later replay |
start_replay_session |
Start an rr replay session; accepts trace_dir from rr_record, or omit to replay the latest recording |
A replay session works with all standard tools, plus dedicated reverse-execution tools:
| Tool | Description |
|---|---|
reverse-continue |
Run backwards to the previous breakpoint or watchpoint |
reverse-step |
Step backwards one source line or instruction (enters calls) |
reverse-next |
Step backwards one source line or instruction (skips calls) |
reverse-finish |
Run backwards to where the current function was called |
Typical workflow:
rr_record("/path/to/binary", args=["--flag"])
→ { "trace_dir": "/home/user/.local/share/rr/binary-0", ... }
start_replay_session(trace_dir="/home/user/.local/share/rr/binary-0")
→ { "session_id": "a1b2c3d4", ... }
# Now use the session_id with any tool: breakpoint, run, reverse-continue, etc.
Execution control
Execution tools block until the inferior stops (breakpoint, signal, exit, or
timeout). While blocked, use interrupt to send SIGINT and unblock.
| Tool | GDB command | Description |
|---|---|---|
run |
run |
Start or restart the inferior |
continue_exec |
continue |
Continue after a stop |
step |
step / stepi |
Step into next line or instruction |
next |
next / nexti |
Step over next line or instruction |
finish |
finish |
Run until current function returns |
until |
until |
Run until a specific location (skip loops) |
interrupt |
SIGINT | Interrupt a running inferior |
Breakpoints and watchpoints
| Tool | GDB command | Description |
|---|---|---|
breakpoint |
break / tbreak |
Set a breakpoint (supports conditions) |
delete_breakpoints |
delete |
Delete one or all breakpoints |
watch |
watch / rwatch / awatch |
Stop when an expression is written, read, or accessed |
Threads
| Tool | GDB command | Description |
|---|---|---|
list_threads |
info threads |
List all threads with their current location |
select_thread |
thread N |
Switch to a specific thread |
Stack frames
| Tool | GDB command | Description |
|---|---|---|
backtrace |
backtrace |
Show the full call stack |
select_frame |
frame N |
Select a frame by number |
up |
up |
Move up toward the caller |
down |
down |
Move down toward the innermost frame |
Inspection
| Tool | GDB command | Description |
|---|---|---|
context |
frame + info args + info locals + list | Full snapshot of current location, arguments, locals, and source — call this after every stop |
list_variables |
info locals / info args |
Variables in the current frame |
print |
print |
Evaluate and print a GDB expression |
examine |
x |
Examine memory at an address |
info_registers |
info registers |
Show CPU register values |
list_source |
list |
Show source code around the current position |
disassemble |
disassemble |
Disassemble a function or address range |
Generic
| Tool | Description |
|---|---|
exec_command |
Run any GDB command and return its output |
batch_commands |
Run a list of commands sequentially (fewer round-trips) |
exec_command handles execution commands correctly: advance, jump,
signal, and return all block until the inferior stops, just like the named
tools do.
Notes
GDB plugins such as pwndbg or GEF work if installed, but their custom prompts (`(
Tools (34)
start_sessionSpawn a GDB process, optionally loading a binarystop_sessionKill a session and free its resourceslist_sessionsShow all active sessions with idle time and kindrr_recordRecord a program executionstart_replay_sessionStart an rr replay sessionreverse-continueRun backwards to the previous breakpoint or watchpointreverse-stepStep backwards one source line or instructionreverse-nextStep backwards one source line or instruction (skips calls)reverse-finishRun backwards to where the current function was calledrunStart or restart the inferiorcontinue_execContinue after a stopstepStep into next line or instructionnextStep over next line or instructionfinishRun until current function returnsuntilRun until a specific locationinterruptInterrupt a running inferiorbreakpointSet a breakpointdelete_breakpointsDelete one or all breakpointswatchStop when an expression is written, read, or accessedlist_threadsList all threads with their current locationselect_threadSwitch to a specific threadbacktraceShow the full call stackselect_frameSelect a frame by numberupMove up toward the callerdownMove down toward the innermost framecontextFull snapshot of current location, arguments, locals, and sourcelist_variablesVariables in the current frameprintEvaluate and print a GDB expressionexamineExamine memory at an addressinfo_registersShow CPU register valueslist_sourceShow source code around the current positiondisassembleDisassemble a function or address rangeexec_commandRun any GDB command and return its outputbatch_commandsRun a list of commands sequentiallyConfiguration
claude_desktop_config.json
{"mcpServers": {"gdb": {"command": "uv", "args": ["tool", "run", "gdb-mcp"]}}}Try it
→Start a GDB session for my binary at ./build/app and set a breakpoint at main.
→Run the program and show me the backtrace when it hits the breakpoint.
→Record this execution using rr so I can perform reverse debugging.
→Step backwards through the code to find where the variable 'x' was modified.
→Examine the memory at the current stack pointer address.