pwndbg-mcp is an MCP server that enables an AI agent to interact with and debug ELF binaries using pwndbg via GDB. It exposes a set of GDB-related capabilities through the MCP interface, including loading executables, issuing debug commands, inspecting process state, and interacting with pwndbg features like context, heap, and vmmap. The server defaults to listening on localhost:8780 and uses an HTTP streamable transport, enabling integration with agents that communicate over HTTP/SSE. Available tools include commands to load executables into the debug session, send commands to the debugger, read and interrupt the process, and utilize pwndbg aliases for quick inspection of program state. It also supports decomp2dbg integration through a dedicated command pathway to display decompiled sections when connected. When running locally, you can interact with pwndbg-mcp via the provided CLI options or through UV to manage dependencies and execution environments.

Prerequisites:

• Python 3.10+ installed on your system
• Git installed
• Optional: the UV toolchain for Python-based MCP tooling

Install steps:

1. Clone the repository: git clone https://github.com/RocketMaDev/pwndbg-mcp.git cd pwndbg-mcp

2. Install dependencies and run via UV (recommended):

   ensure uv is installed, then sync/build the environment

   uv sync uv run pwndbg-mcp

3. Alternative: run directly from source without UV:

   create a virtual environment and install dependencies if needed

   python -m venv .venv source .venv/bin/activate pip install -r requirements.txt # if a requirements file exists python pwndbg_mcp/main.py

4. Optional: install as a local tool for easy access: uv tool install .

   run from any path

   pwndbg-mcp

5. If you prefer containerized usage, wrap pwndbg-mcp in a minimal container as described in the README to avoid path issues.

Notes and tips:

• By default, pwndbg-mcp runs on localhost:8780 with gdb as the main pwndbg binary and /mcp as the MCP connection endpoint using HTTP transport. You can adjust transport and port with CLI options.
• Exercise caution: the tools load_executable, execute_command, and eval_to_send_to_process can execute arbitrary code within the debugger context. Do not expose the service publicly without isolation.
• For environments where agents expect a containerized filesystem layout, consider wrapping pwndbg-mcp in a minimal container (e.g., bwrap) to preserve working directory assumptions.
• If you enable decomp2dbg features, ensure proper network access to the decomp2dbg endpoint via the provided d2d options.
• Default tools include GDB-related capabilities, process interaction capabilities (send_to_process, read_from_process, interrupt_process), and pwndbg aliases for rapid inspection (e.g., context, heap, vmmap).