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_commandtool 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:
- Start a session —
pwndbg_startspawns an LLDB+pwndbg process - Load a binary —
pwndbg_loadloads an executable for analysis - Set breakpoints —
pwndbg_breaksets breakpoints by symbol or address - Run and step —
pwndbg_run,pwndbg_step,pwndbg_next, etc. - Inspect state — registers, memory, stack, heap, disassembly
- 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