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)

Installation
------------

Clone the repository and install dependencies with `uv <https://docs.astral.sh/uv/>`_:

.. code-block:: 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:

.. code-block:: 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):

.. code-block:: 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:

.. code-block:: 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, and more
6. **Exploit development** — ROP gadgets, cyclic patterns, patching, shellcode

All 146 tools are documented in the :doc:`api` reference.