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

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