Gdbstub MCP

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:

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:

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.