Multi-session GDB control for Codex, Claude Code, and any MCP client.

gdb-mcp is a Model Context Protocol server that drives GDB through GDB/MI. It gives AI coding clients a structured, session-aware debugger interface for local Linux programs, core files, and gdbserver targets.

The default gdb-mcp command is a lazy stdio proxy. MCP clients can discover tools immediately, while the full backend starts only when the first gdb_* tool is called.

• Isolated debugging sessions: every target gets an explicit session_id, so multiple programs can be debugged side by side.
• Compact context tools: run, continue, step, reverse-step, and inspect with tool responses that include the current frame, backtrace, locals, and summary.
• Local and remote workflows: debug local executables, attach to Linux processes, load core files, connect to gdbserver, or launch a managed gdbserver.
• Agent-readable capabilities: expose workflow groups, output strategy, safety posture, dependency versions, and diagnostic state through structured read-only tools.
• Safety by default: reads and ordinary debugger control are available out of the box; raw GDB execution, inferior calls, mutation, and memory writes require explicit unsafe mode.

• Python 3.10 or newer.
• Linux for supported local debugging.
• GDB on PATH; optional gdbserver for remote or managed-server workflows.
• Optional rr on PATH for native record/replay workflows.
• uv for the recommended Git-based install.

On Debian/Ubuntu:

sudo apt-get install -y gcc gdb
# Optional workflow dependencies:
sudo apt-get install -y gdbserver rr

codex plugin marketplace add BeaCox/gdb-mcp --ref v0.4.0
codex plugin add gdb-mcp@beacox

Or register the MCP server directly:

codex mcp add gdb -- \
  uvx --from git+https://github.com/BeaCox/gdb-mcp.git@v0.4.0 gdb-mcp

claude plugin marketplace add BeaCox/gdb-mcp@v0.4.0
claude plugin install gdb-mcp@beacox --scope user

Or register the MCP server directly:

claude mcp add --scope user gdb -- \
  uvx --from git+https://github.com/BeaCox/gdb-mcp.git@v0.4.0 gdb-mcp

For local development:

uv sync --extra dev
codex mcp add gdb -- uv run gdb-mcp
# or
claude mcp add --scope user gdb -- uv run gdb-mcp

The universal installer is also available:

uvx --from git+https://github.com/BeaCox/gdb-mcp.git@v0.4.0 gdb-mcp --install
uvx --from git+https://github.com/BeaCox/gdb-mcp.git@v0.4.0 gdb-mcp --install --direct

Print portable client configuration:

gdb-mcp --print-config

The client-facing gdb-mcp command is a lazy stdio proxy. Client startup, initialize, ping, and tools/list do not start GDB or the full backend; the backend is created only when the first tool is called.

For the fastest repeated startup, prefer an installed plugin or an already installed gdb-mcp command. Direct uvx --from git+... registrations are portable, but the first run after a new tag, cold cache, or network/cache failure can still spend time resolving and preparing the package before the lazy proxy starts.

Release checks include:

uv run python scripts/check_lazy_startup.py

Use the latest release tag listed in CHANGELOG.md, then restart the MCP client after updating.

For Codex plugin installs, replace the pinned marketplace snapshot and reinstall the plugin cache:

codex plugin marketplace remove beacox
codex plugin marketplace add BeaCox/gdb-mcp --ref <new-tag>
codex plugin add gdb-mcp@beacox

For Claude Code plugin installs pinned to a release tag, replace the marketplace source and reinstall the plugin cache:

claude plugin marketplace remove beacox
claude plugin marketplace add BeaCox/gdb-mcp@<new-tag>
claude plugin install gdb-mcp@beacox --scope user

If your Claude Code marketplace was intentionally left unpinned, refresh it and update the installed plugin instead:

claude plugin marketplace update beacox
claude plugin update gdb-mcp@beacox --scope user

For direct MCP registrations, replace the tag in the registered uvx --from source. Current Codex CLI releases replace an existing gdb server when the same name is added again. For Claude Code, remove the old direct registration first if gdb is already configured:

codex mcp add gdb -- \
  uvx --from git+https://github.com/BeaCox/gdb-mcp.git@<new-tag> gdb-mcp

# If Claude Code already has a direct gdb registration:
claude mcp remove --scope user gdb
claude mcp add --scope user gdb -- \
  uvx --from git+https://github.com/BeaCox/gdb-mcp.git@<new-tag> gdb-mcp

For installer-managed configs, rerun the installer with the newer tag:

uvx --from git+https://github.com/BeaCox/gdb-mcp.git@<new-tag> gdb-mcp --install
uvx --from git+https://github.com/BeaCox/gdb-mcp.git@<new-tag> gdb-mcp --install --direct

Open a new Codex or Claude Code session after installation and ask for a GDB debugging task:

Use GDB MCP to debug /tmp/gdb-mcp-hello. Set a breakpoint at add, run, show the
current location, backtrace, locals, then continue once.

Typical MCP tool flow:

1. gdb_create_session with an executable path.
2. Optional: gdb_server_health and gdb_capabilities to inspect dependency availability, output limits, safety mode, and recommended workflows.
3. gdb_set_breakpoint.
4. gdb_run_and_context, gdb_continue_and_context, gdb_step_and_context, or gdb_next_and_context.
5. Inspect further with gdb_context, gdb_eval_expression, gdb_registers, or gdb_read_memory.
6. For stripped or optimized binaries, switch to pwn-oriented tools such as gdb_pwn_context, gdb_binary_summary, gdb_register_context, gdb_address_info, gdb_rva_info, gdb_symbols, gdb_got, gdb_nearpc, gdb_telescope, and gdb_vmmap_structured.
7. For time-travel debugging, use gdb_rr_record to capture a run and gdb_start_rr_replay_session to inspect it, or use gdb_start_recording before a live GDB run. Then call gdb_reverse_continue_and_context, gdb_reverse_step_and_context, or gdb_reverse_next_and_context.
8. gdb_close_session when finished.

Every session has an explicit session_id; there is no implicit current session. The *_and_context tools return a compact summary, current frame, backtrace, and locals. Pass include_raw=true when the raw GDB/MI payload is needed.

See examples/README.md for a Linux walkthrough and TOOLS.md for the full tool reference.

MCP client
  |
  | stdio
  v
gdb-mcp lazy proxy
  |
  | starts on first gdb_* tool call
  v
gdb-mcp backend
  |
  | GDB/MI
  v
GDB / gdbserver / target program

gdb-mcp normally starts the backend lazily. To run a standalone HTTP backend:

gdb-mcp-backend --transport streamable-http --host 127.0.0.1 --port 8000
GDB_MCP_BACKEND_URL=http://127.0.0.1:8000/mcp gdb-mcp

The default bind address is loopback. Do not expose the HTTP transport to an untrusted network without authentication and host isolation.

Raw GDB execution, inferior function calls, variable mutation, memory writes, and breakpoint command lists are disabled by default. Enable them explicitly:

gdb-mcp --unsafe
# or
GDB_MCP_ALLOW_UNSAFE=1 gdb-mcp

Unsafe tools can execute target code, modify process state, or run arbitrary GDB behavior. Use them only for trusted targets.

uv sync --extra dev
uv run ruff check .
uv run pytest
uv build

Support policy and release notes live in CHANGELOG.md. Security guidance is in SECURITY.md.

• Tool reference
• Linux walkthrough
• Security policy
• Changelog