pygdbmi

This MCP server provides a collection of GDB-related tools exposed via the MCP protocol. It is built on top of pygdbmi and allows you to control a debugging session remotely: load binaries, connect to local or remote debuggers, set breakpoints, read memory, disassemble code, and inspect context such as registers and stack. Key tools include execute (run arbitrary GDB commands), run (execute the loaded binary), interrupt (pause), finish (continue until the current function returns), step_control (step, next, continue, stepi, nexti), target_remote (connect to gdbserver), disconnect, set_file and set_poc_file (load executables and PoC data), get_session_info (session metadata), and various breakpoint and memory inspection tools (set_breakpoint, list_breakpoints, delete_breakpoint, toggle_breakpoint, get_memory, disassemble, get_context).

To use it, start the server via your environment’s MCP runner (the example uses UV to run the Python package). Once running, you can interact with the exposed MCP endpoints or client libraries to issue MCP commands that map to GDB operations. Remote debugging over streamable-http is supported, so clients can connect over HTTP/SSE to drive the debugger from a remote location. Typical workflows include loading the target binary with set_file, connecting to a gdbserver with target_remote, setting initial breakpoints, and then stepping through or running the program while querying context and memory as needed.

Prerequisites:

• Python 3.13+ (recommended) and a working Python environment
• UV (https://uv.sh) for managing the environment and running the server
• pygdbmi and project dependencies (installed via the package in this repo)

Step-by-step:

1. Clone the repository

git clone https://github.com/cnitlrt/pygdbmi-mcp-server
cd pygdbmi-mcp-server

2. Install dependencies and set up the environment (using uv as described in the README):

# Create a virtual environment and install the package
uv venv --python 3.13
# Activate the virtual environment
# Linux/macOS
source .venv/bin/activate
# Windows
# .venv\Scripts\activate

# Install the project in editable mode
uv pip install -e .

3. Configure environment variables (example values shown):

# Example .env values to customize at runtime
echo 'PORT=1111' > .env
echo 'HOST="0.0.0.0"' >> .env
echo 'TRANSPORT="streamable-http"' >> .env
echo 'GDB_PATH="gdb"' >> .env

4. Run the server:

uv run pygdbmi-mcp-server

You can override transport mode at runtime:

uv run pygdbmi-mcp-server --transport streamable-http
uv run pygdbmi-mcp-server --transport stdio

Tips and common considerations:

• If using streamable-http, ensure you expose the server to the network and configure the correct HOST/PORT.
• On Windows, GDB defaults and pwndbg behavior may differ; the server gracefully degrades to standard GDB commands if pwndbg features are unavailable.
• The GDB_PATH variable controls which debugger executable is used; point it at gdb or pwndbg-enabled binaries as needed.
• When loading binaries, use set_file to load the symbol file for accurate debugging information. Use target_remote to connect to gdbserver when debugging remotely.
• If you encounter issues with memory or context retrieval, ensure your GDB setup supports the required commands and that the connected target is in a valid state.
• For remote debugging, the default MCP SSE/HTTP endpoint is /mcp; connect clients accordingly (e.g., http://<server>:1111/mcp).