pwndbg-mcp

pwndbg-mcp

Model Context Protocol server that gives AI agents full access to GDB/pwndbg debugging and pwntools exploit development utilities. 96 tools across live debugging, heap analysis, and offline binary analysis.

What it does

• Live debugging -- Load binaries, set breakpoints, step through code, inspect registers/memory/stack
• pwndbg integration -- Context display, telescope, vmmap, heap visualization, ROP gadgets, exploit helpers
• Process I/O -- Send/receive data to the debugged process stdin/stdout via PTY
• pwntools offline -- Packing, cyclic patterns, ELF analysis, ROP chain building, shellcode generation, format string payloads

Requirements

• Python >= 3.11
• GDB with pwndbg installed
• uv package manager

Quick start

git clone https://github.com/echo8134/pwndbg-mcp.git && cd pwndbg-mcp
uv run pwndbg-mcp install

This installs dependencies and registers the server in ~/.claude.json. Restart Claude Code to pick it up.

CLI

pwndbg-mcp              # run the MCP server (default)
pwndbg-mcp install      # uv sync + register in ~/.claude.json
pwndbg-mcp uninstall    # unregister from ~/.claude.json
pwndbg-mcp config       # show registration status and JSON config
pwndbg-mcp run          # run the MCP server (explicit)
pwndbg-mcp path         # add pwndbg-mcp to shell PATH (zsh/bash/fish)

Configuration

Environment Variable	Default	Description
PWNDBG_MCP_GDB_PATH	gdb	Path to GDB binary (with pwndbg loaded)

Tools (96)

GDB Core (33)

Tool	Description
load_binary	Load an ELF binary into GDB for debugging
attach_process	Attach GDB to a running process by PID
detach_process	Detach GDB from the current process
remote_connect	Connect to a remote GDB server (gdbserver)
remote_disconnect	Disconnect from a remote GDB target
run_program	Start running the loaded program from the beginning
continue_execution	Continue program execution until next breakpoint or exit
step_into	Step into the next source line (enters function calls)
step_over	Step over the next source line (skips into function calls)
step_instruction	Step one machine instruction (enters calls)
next_instruction	Step one machine instruction (skips calls)
finish_function	Execute until the current function returns
interrupt_execution	Interrupt a running program (like Ctrl-C in GDB)
kill_program	Kill the running program
set_breakpoint	Set a breakpoint at the specified location
delete_breakpoint	Delete a breakpoint by its number
enable_breakpoint	Enable a disabled breakpoint
disable_breakpoint	Disable a breakpoint without deleting it
list_breakpoints	List all breakpoints, watchpoints, and catchpoints
set_watchpoint	Set a watchpoint on a memory expression
read_registers	Read CPU register values
write_register	Write a value to a CPU register
read_memory	Read raw memory bytes at an address
write_memory	Write bytes to memory at an address
disassemble	Disassemble instructions at an address or range
evaluate_expression	Evaluate an expression in the current context
backtrace	Show the call stack (backtrace)
stack_locals	Show local variables in the current stack frame
stack_args	Show function arguments in the current stack frame
select_frame	Select a stack frame by number
list_threads	List all threads in the debugged process
switch_thread	Switch to a different thread
execute_command	Execute any raw GDB/MI or console command

pwndbg Extensions (41)

Tool	Description
pwndbg_context	Show pwndbg context display: registers, disassembly, stack, backtrace
telescope	Dereference pointers recursively starting from an address
vmmap	Show virtual memory map of the process
hexdump_memory	Hex dump memory at an address
xinfo	Show information about what a memory address belongs to
search_memory	Search process memory for a value
probeleak	Probe memory for pointers to known regions (heap, stack, libc, etc.)
leakfind	Find chains of pointers starting from an address to known regions
distance	Calculate the distance between two addresses
heap_bins	Show all free list bins (tcache, fast, unsorted, small, large)
heap_overview	Show an overview of the heap state
vis_heap_chunks	Visual representation of heap chunks with color-coded boundaries
malloc_chunk	Inspect a specific malloc chunk header and metadata
top_chunk	Show the top (wilderness) chunk of the heap
heap_arenas	List all malloc arenas
tcachebins	Show tcache bin entries and their contents
fastbins	Show fast bin entries and their contents
unsortedbin	Show unsorted bin entries
smallbins	Show small bin entries and their contents
largebins	Show large bin entries and their contents
find_fake_fast	Find candidate locations for fake fastbin chunks near an address
try_free	Simulate what free() would do on a chunk, checking for errors
checksec	Show binary security features: NX, PIE, RELRO, stack canary, FORTIFY
got_table	Show Global Offset Table entries and their resolved addresses
plt_table	Show Procedure Linkage Table entries
piebase	Show the PIE base address of the loaded binary
elf_sections	List all ELF sections of the loaded binary
libcinfo	Show libc version and path information
rop_gadgets	Find ROP gadgets in the loaded binary
cyclic_pattern	Generate a De Bruijn cyclic pattern for finding offsets
cyclic_find	Find the offset of a value in the De Bruijn cyclic pattern
onegadget	Find one-gadget RCE candidates in libc
canary	Show the current stack canary value
retaddr	Show return addresses on the stack for the current frame
sigreturn_frame	Generate a sigreturn frame for SROP exploitation
dumpargs	Dump function arguments at the current position based on calling convention
patch_instruction	Patch an instruction in memory at the given address
nearpc	Show disassembly around an address with context
emulate	Emulate execution of instructions without actually running them
pwndbg_status	Return the current GDB state and drain any pending messages
pwndbg_hard_reset	Kill and restart the GDB process completely

Process I/O (4)

Tool	Description
send_to_process	Send a string to the debugged process's stdin
eval_to_send	Evaluate a Python/pwntools expression and send the result as bytes to the process
read_from_process	Read output from the debugged process's stdout
interrupt_process	Send a control signal to the debugged process via the terminal

pwntools Utilities (18)

Offline helpers that don't require a running GDB session.

Tool	Description
pack	Pack an integer into bytes
unpack	Unpack a hex string into an integer
pwn_cyclic	Generate a De Bruijn cyclic pattern for buffer overflow offset finding
pwn_cyclic_find	Find the offset of a value in the De Bruijn cyclic pattern
elf_info	Get basic ELF info: architecture, bits, endianness, and security checksec results
elf_symbols	List symbols defined in an ELF binary
elf_got	Show Global Offset Table (GOT) entries of an ELF binary
elf_plt	Show Procedure Linkage Table (PLT) entries of an ELF binary
elf_search	Search an ELF binary for a byte string
rop_find_gadgets	Find ROP gadgets in an ELF binary
rop_build_chain	Build a ROP chain from a JSON specification
shellcraft_generate	Generate shellcode assembly source from pwntools shellcraft templates
asm_encode	Assemble instructions into machine code bytes
asm_decode	Disassemble machine code bytes into assembly instructions
fmtstr_payload	Generate a format string exploit payload
hex_encode	Encode a string to its hex representation
hex_decode	Decode a hex string back to text or byte representation
xor_data	XOR a hex data string with a hex key string

Architecture

src/
  server.py           MCP server entry point, GDB controller lifecycle
  gdb_controller.py   Async GDB/MI protocol handler with PTY for process I/O
  tools_gdb.py        GDB core tools (33)
  tools_pwndbg.py     pwndbg extension tools (41)
  tools_pwntools.py   Offline pwntools utilities (18)
  tools_process.py    Process stdin/stdout tools (4)
  utils.py            ANSI stripping, response formatting
  cli.py              CLI: install/uninstall/config/run/path