pwndbg-lldb-mcp

An MCP server that exposes pwndbg commands running under LLDB as tools for AI assistants. This enables AI-driven binary analysis, exploit development, and reverse engineering through pwndbg's enhanced debugging capabilities.

Features

• 146 tools spanning 18 categories of pwndbg and LLDB functionality
• Session isolation — each debugging session runs in its own LLDB process, identified by UUID
• Async PTY communication — commands are sent over a pseudo-terminal with prompt detection and 30-second timeouts
• Escape hatch — the pwndbg_command tool can run any pwndbg or LLDB command directly

Tool Categories

Category	Examples
Session Management	start, terminate, list sessions
Program Loading	load executable, attach to process, load core dump
Execution Control	run, step, next, finish, continue, nextjmp, nextcall, nextret
Breakpoints & Watchpoints	set, delete, enable/disable
Context & Display	pwndbg context — registers, disassembly, stack, backtrace
Memory Inspection	telescope, hexdump, vmmap, search, read/write
Registers & CPU State	read/write registers, FPU, CPUID
Disassembly	nearpc, pdisass, emulate (Unicorn)
Stack & Arguments	argv, retaddr, dumpargs, canary, backtrace
ELF / Binary Analysis	checksec, GOT/PLT, PIE offsets, ELF headers
Heap Analysis	glibc ptmalloc2 — arena, bins, chunks, tcache
Exploit Development	cyclic patterns, ROP gadgets, patching, assembler, XOR
Process Information	procinfo, ASLR, auxv, libc info, errno
WinDbg Compatibility	db, dw, dd, dq memory dump commands
Darwin / macOS	commpage, plist
Configuration & Meta	config, theme, tips, version
LLDB Native	expression eval, type lookup, image list
Kernel Debugging	kchecksec, ksymbol, slab, paging (via QEMU/kgdb)

Quick Start

Prerequisites

• Python 3.10+
• LLDB with pwndbg installed
• An MCP-compatible AI client (e.g. Claude Desktop, Claude Code)

Install

git clone https://github.com/Micro-Evaluation-Group/pwndbg-lldb-mcp.git
cd pwndbg-lldb-mcp
uv sync

This creates a .venv/ with all dependencies installed. The MCP server must be run using this venv's Python binary so that mcp and other dependencies are available. If you're already running inside the activated venv, you can use python directly; otherwise, use the full path to the venv binary.

Claude Code

Add the MCP server to your project, using the venv's Python binary:

claude mcp add pwndbg-lldb -- /path/to/pwndbg-lldb-mcp/.venv/bin/python /path/to/pwndbg-lldb-mcp/pwndbg_lldb_mcp.py

Or add it globally (available in all projects):

claude mcp add --scope user pwndbg-lldb -- /path/to/pwndbg-lldb-mcp/.venv/bin/python /path/to/pwndbg-lldb-mcp/pwndbg_lldb_mcp.py

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json, pointing to the venv's Python binary:

{
  "mcpServers": {
    "pwndbg-lldb": {
      "command": "/path/to/pwndbg-lldb-mcp/.venv/bin/python",
      "args": ["/path/to/pwndbg-lldb-mcp/pwndbg_lldb_mcp.py"]
    }
  }
}

Usage

Once connected, the AI assistant can:

1. Start a session — pwndbg_start spawns an LLDB+pwndbg process
2. Load a binary — pwndbg_load loads an executable for analysis
3. Set breakpoints — pwndbg_break sets breakpoints by symbol or address
4. Run and step — pwndbg_run, pwndbg_step, pwndbg_next, etc.
5. Inspect state — registers, memory, stack, heap, disassembly
6. Exploit development — ROP gadgets, cyclic patterns, patching, shellcode

Documentation

Read the docs online — built automatically on every push to main.

• Quick Start — installation, configuration, usage
• Architecture — PTY communication, session model, tool categories
• API Reference — all 146 tools with full docstrings

Build locally

pip install -e ".[docs]"
make -C docs html
open docs/_build/html/index.html

License

MIT