Gdbstub MCP server

gdbstub-mcp

Let your AI agent debug a kernel, and tell you why it triple-faulted.

<!-- mcp-name: io.github.0xmortuex/gdbstub-mcp -->

gdbstub-mcp is an MCP server that gives AI agents (Claude Code, or any MCP client) a debugger for bare-metal code running in QEMU. It speaks the GDB Remote Serial Protocol directly to QEMU's built-in gdbstub, so you don't need a gdb binary. That matters most on Windows and macOS, where a cross-architecture gdb is a pain to get.

It's the companion to qemu-mcp. qemu-mcp lets an agent boot a kernel and see the crash. gdbstub-mcp lets it find out why.

What it looks like

An agent debugging a hobby kernel. This is real output, captured from the test kernel in tests/fixtures/kernel:

> debug_break kernel.c:10
#1 sw breakpoint at 0x100029 <add+0x9> at kernel.c:10

> debug_continue
Stopped: SIGTRAP (breakpoint/step) - breakpoint #1 (kernel.c:10)
pc = 0x100029 <add+0x9> at kernel.c:10
next: mov eax, dword ptr [ebp + 8]

> debug_backtrace
#0  0x100029 <add+0x9> at kernel.c:10
#1  0x100071 <compute+0x31> at kernel.c:16
#2  0x1000b2 <kmain+0x12> at kernel.c:28
#3  0x100016 <_start+0xa> at boot.s:21

> debug_registers eip,eflags,cr0
     eip = 0x00100029  <add+0x9> at kernel.c:10
  eflags = 0x00000093  [SF AF CF]
     cr0 = 0x00000011  [ET PE]

And when the machine silently reboots, debugexplainfault reads QEMU's interrupt log and explains the crash:

> debug_explain_fault
A TRIPLE FAULT occurred: the CPU reset itself.

[0] #UD invalid opcode at triple_fault+0xa (kernel.c:23)
[1] #GP general protection fault at triple_fault+0xa (kernel.c:23)
     selector 0x32: IDT entry 6 = #UD
     -> the IDT entry for vector 0x6 is missing or invalid - the CPU couldn't
        even start your handler. ...
[2] #DF double fault at triple_fault+0xa (kernel.c:23)

Root cause: the chain started with #UD at triple_fault+0xa.
It escalated to a triple fault because the handler for #UD (IDT entry 0x6)
could not be invoked. Fix the IDT entry so the original exception reaches
your handler, then fix the #UD itself.

A real QEMU log of a crash is thousands of lines of timer interrupts and register dumps. This tool picks out the exception chain, decodes the error codes, and points at the cause.

Why another debugger MCP?

Existing GDB MCP servers wrap a gdb binary and target userland programs or core dumps. The embedded ones target microcontrollers through probe-rs or OpenOCD. None of them is built for the osdev loop: a kernel you wrote yourself, running in QEMU, crashing before it can print anything.

pip install gdbstub-mcp and you're set.

• No gdb required. It's pure Python (pyelftools + capstone). Run

target.xml. Control registers (CR0/CR2/CR3/CR4, EFER) are there on x86, and flag registers are decoded.

• Any architecture QEMU supports. The register layout comes from the stub's own

every stop shows function+offset at file:line. Prefixed ABIs work too: kmain resolves to mort_kmain when that name is unique.

• Symbols and source lines. Break on kmain, kmain+0x10 or kernel.c:42, and

handles x86 prologues and epilogues correctly. For -O2 kernels without frame pointers it can scan the stack for return addresses instead.

• Backtraces that work on real kernels. It walks the frame-pointer chain, and

another tool that does this.

• Triple-fault diagnosis. debugexplainfault, described above. I haven't found

Install

pip install gdbstub-mcp

Claude Code:

claude mcp add gdbstub -- gdbstub-mcp

Other MCP clients use the same idea: run gdbstub-mcp as a stdio server. Python 3.10+.

Usage

Start QEMU with its gdbstub on, with the CPU halted:

qemu-system-i386 -kernel kernel.elf -s -S -d int,cpu_reset -D int.log -no-reboot

Shortened. The full README is on GitHub.