Quick Start

Prerequisites

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

Installation

Clone the repository and install dependencies with uv:

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_start spawns an LLDB+pwndbg process
Load a binary — pwndbg_load loads an executable for analysis
Set breakpoints — pwndbg_break sets breakpoints by symbol or address
Run and step — pwndbg_run, pwndbg_step, pwndbg_next, etc.
Inspect state — registers, memory, stack, heap, disassembly, and more
Exploit development — ROP gadgets, cyclic patterns, patching, shellcode

All 146 tools are documented in the API Reference reference.