gdb-mcp

Experimental — expect rough edges and breaking changes.

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 for rr_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 ((pwndbg), gef>) will break session startup. Either avoid them or force the standard prompt in .gdbinit:

set prompt (gdb)

Timeout behaviour: if an execution command times out, the session is in an indeterminate state. Call interrupt to stop the inferior, wait for the blocked tool call to return, then resume normally. When in doubt, stop_session

• start_session gives a clean slate.