# pwndbg-lldb-mcp

An [MCP](https://modelcontextprotocol.io/) server that exposes [pwndbg](https://pwndbg.re) 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](https://lldb.llvm.org/) with [pwndbg](https://pwndbg.re) installed
- An MCP-compatible AI client (e.g. Claude Desktop, Claude Code)

### Install

```bash
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:

```bash
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):

```bash
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:

```json
{
  "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](https://micro-evaluation-group.github.io/pwndbg-lldb-mcp/)** — built automatically on every push to `main`.

- [Quick Start](https://micro-evaluation-group.github.io/pwndbg-lldb-mcp/quickstart.html) — installation, configuration, usage
- [Architecture](https://micro-evaluation-group.github.io/pwndbg-lldb-mcp/architecture.html) — PTY communication, session model, tool categories
- [API Reference](https://micro-evaluation-group.github.io/pwndbg-lldb-mcp/api.html) — all 146 tools with full docstrings

### Build locally

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

## License

MIT