gdb-mcp

# gdb-mcp Model Context Protocol server that wraps `gdb` so an LLM can drive live debugging sessions. The server exposes tools for starting a session on a binary, attaching to an existing PID, running ad-hoc commands, batching commands, checking status, and shutting sessions down. > Requires `gdb` on the host and the `mcp` python package (v1+). ## Setup Install from PyPI (preferred): ```bash pip install gdb-mcp ``` You can also install from source, inside a virtualenv (recommended) or directly: ```bash # optional but recommended python -m venv .venv . .venv/bin/activate pip install -e . # or: pip install . ``` ## Running the MCP server You can start the server directly: ```bash gdb-mcp # or python -m gdb_mcp.server ``` The server uses stdio for transport (the default for most MCP clients). Point your MCP client configuration at the command above. ### One-shot client configuration Run `gdb-mcp --install` to add the server to any detected MCP-aware clients without editing config files by hand. The installer currently knows how to update: - Codex CLI (`~/.codex/config.toml`) - Claude Desktop configs (common Linux/macOS paths) - Cursor / Windsurf MCP config files (if present) Use `--install-command /custom/path/to/gdb-mcp` or `--install-args ...` if you need to override what gets written. ## Exposed tools - `start_binary(binary_path, args=None, cwd=None, load_init=True, start_timeout=30.0, prompt=None, force_prompt=True)` – launch gdb against a target binary (with optional args) and return a session id and the initial banner. Set `load_init=False` to skip user gdbinit (default is to load it so helpers like GEF/pwndbg remain enabled). Increase `start_timeout` if loading extensions takes longer to reach the first prompt. Use `prompt` to force a specific prompt string (defaults cover `(gdb)`, `(pwndbg)`, and `gef>`). `force_prompt` sets the prompt to the chosen value after startup to avoid timeouts from customized prompts (e.g., pwndbg); set `force_prompt=False` if you need to keep your custom prompt unchanged. - `attach_to_pid(pid, cwd=None, load_init=True, start_timeout=30.0, prompt=None, force_prompt=True)` – start gdb and attach to a running process (same `load_init`/timeout/prompt behavior as above). - `gdb_command(session_id, command, timeout_seconds=15.0)` – execute a single gdb command in the given session and return the output. - `batch_commands(session_id, commands, timeout_seconds=15.0)` – run a list of commands sequentially. - `list_sessions()` – get a snapshot of all active sessions. - `session_status(session_id)` – check if the gdb process is still alive. - `stop_session(session_id)` – shut down the gdb process and remove it. Each tool returns simple JSON so it is easy to route back into your LLM prompt. ## Notes and tips - The server automatically disables pagination and confirmation prompts and enables pending breakpoints to keep interactions non-blocking. - `timeout_seconds` applies per command. If you expect a program to run for a long time, pass a larger timeout or `None`. - Output is captured from gdb stdout/stderr until the next `(gdb)` prompt. If you spawn a program that never returns to the prompt (e.g., it blocks on input), the call will time out. - Common debugger prompts are detected automatically (`(gdb)`, `(pwndbg)`, `gef>`), even with ANSI colors. You can still pass a custom `prompt` if you use something nonstandard. By default the server forces the prompt to a stable value (`force_prompt=True`) so gdbinit customizations (like pwndbg) don’t prevent the initial prompt from being detected. ## Demo Auto-playing preview:  Source video: `docs/media/demo.mp4` ## Credits - This project was built for my CSE 598 class, which emphasized using AI/LLMs in our workflow. I leaned on AI to write the entire project—including this README. - Inspired by https://github.com/mrexodia/ida-pro-mcp, and their server logic was used as a starting point.