# 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](https://docs.astral.sh/uv/)
- GDB on `$PATH`
- [rr](https://rr-project.org/) on `$PATH` (optional — only needed for `rr_record` / `start_replay_session`)

## Installation

```bash
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:

```bash
uv tool upgrade gdb-mcp
```

### Install and configure Gemini CLI

```bash
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](https://rr-project.org/) 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.