# gdbstub-mcp [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/0xmortuex/gdbstub-mcp  
**GitHub Stars:** 1  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/gdbstub-mcp

## Description
Debug kernels through QEMU's gdbstub with no gdb binary - and explain triple faults.

## Tools
Capabilities this server exposes over MCP:

- **debug_connect** — Connect to a gdbstub (`port`, default 1234) and optionally load an `elf` with symbols. Several named sessions can be open at once.
- **debug_disconnect** — Remove breakpoints, detach (the guest keeps running) and close the session.
- **debug_sessions** — List sessions: endpoint, running or halted, ELF, breakpoint count.
- **debug_registers** — Read registers: a chosen list, the general set, or `all=True` for control, segment and FPU registers. Flags are decoded and pointers symbolized.
- **debug_set_register** — Write a register.
- **debug_memory** — Read memory as a hexdump, as symbolized pointer-sized `words`, or as a `string`.
- **debug_write_memory** — Write bytes.
- **debug_break** — Set a breakpoint (`sw`, or `hw` for code before paging or not yet loaded) or a watchpoint (`write`, `read`, `access`).
- **debug_delete** — Remove a breakpoint, or list them all.
- **debug_continue** — Resume and wait up to `timeout_s` for a stop. If no stop comes, the target keeps running.
- **debug_wait** — Keep waiting for a stop, or halt the target now (like Ctrl-C).
- **debug_step** — Single-step N instructions.
- **debug_backtrace** — Call stack by frame-pointer chain (`fp`), stack scan (`scan`), or `auto`.
- **debug_disassemble** — Disassemble at an address or the pc. `bits=16` decodes real-mode code.
- **debug_symbol** — Look up an address, symbol or line offline, with no target needed.
- **debug_explain_fault** — Explain a crash or triple fault from a QEMU `-d int,cpu_reset` log (x86).

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "gdbstub-mcp": {
    "command": "uvx",
    "args": ["gdbstub-mcp"]
  }
}
```

## Documentation

## What the gdbstub-mcp MCP server does

gdbstub-mcp connects an MCP client to a program running under QEMU's built-in gdbstub. It implements the GDB Remote Serial Protocol directly, so the debugging process does not require a gdb executable. The primary use case is bare-metal and kernel development, including failures that occur before the program can print useful diagnostics.

The gdbstub-mcp MCP server can load an ELF file for symbols and source-line information. Addresses may be expressed as numeric values, symbols, symbol offsets, source locations, or stack-pointer expressions. Multiple named debugging sessions can remain open at the same time.

## How it works

Start QEMU with its gdbstub enabled and, when needed, paused before the first instruction. A typical setup uses port 1234, QEMU's `-s` option, and `-S` to halt execution. The MCP client then calls `debug_connect`, optionally supplying the ELF file. The server communicates with QEMU over TCP while the agent controls execution through MCP tools.

Symbol data is read locally from the ELF file. It can identify functions, source lines, and offsets in register, memory, breakpoint, disassembly, and backtrace results. Backtraces use a frame-pointer walk when possible; the automatic mode can instead scan the stack for likely return addresses when frame pointers are unavailable.

For x86 crashes, `debug_explain_fault` reads a QEMU log produced with interrupt and CPU-reset logging enabled. It extracts the exception sequence, decodes relevant error information, and identifies how an initial fault escalated to a double or triple fault.

## Setup and configuration

Install the package with:

```bash
pip install gdbstub-mcp
```

The server requires Python 3.10 or newer and runs as a stdio MCP server. Claude Code can register it with:

```bash
claude mcp add gdbstub -- gdbstub-mcp
```

Other MCP clients can launch the same executable as a stdio server. To support fault analysis, configure QEMU to write an interrupt log with `-d int,cpu_reset -D int.log -no-reboot`. The gdbstub port can be changed when connecting; port 1234 is the default.

## Tools and capabilities

The gdbstub-mcp MCP server exposes tools for:

- Opening, closing, and listing named sessions.
- Reading or writing registers, including control, segment, and FPU registers when requested.
- Reading memory as a hexdump, pointer-sized words, or a string, and writing raw bytes.
- Creating software or hardware breakpoints and read, write, or access watchpoints.
- Continuing, interrupting, waiting, and single-stepping execution.
- Generating frame-pointer, stack-scan, or automatic backtraces.
- Disassembling at an address or the current program counter, including 16-bit real-mode decoding.
- Looking up symbols and source lines without an active target.
- Explaining x86 crashes and triple faults from QEMU logs.

## Limitations and notes

This is a machine-level debugger. It provides symbols, source lines, registers, memory, and disassembly, but does not provide source-level `next` or `finish` operations, local-variable inspection, or C-expression evaluation.

Stack scanning is heuristic and can report stale frames. For more reliable backtraces, compile the kernel with frame pointers enabled, such as `-fno-omit-frame-pointer`. Fault explanation supports x86 QEMU logs only. The project is tested against QEMU's gdbstub; other implementations of the remote protocol are untested.

_Full upstream README: https://allmcps.com/mcp/gdbstub-mcp/readme_