gdb-mcp

gdb-mcp is a high-privilege Model Context Protocol (MCP) server that allows Codex to control the GDB debugger via the GDB/MI interface and the pygdbmi library.

Supported deployment architectures for this project:

Windows 上的 Codex
-> Windows 上的 gdb-mcp MCP 服务端
-> Windows 本地 GDB
-> target remote / target extended-remote
-> linux 虚拟机中的 gdbserver
-> 虚拟机内的目标程序

This server is specifically designed for local authorized debugging, CTF Pwn challenges, crash analysis, Core Dump analysis, exploit reproduction, and ELF file analysis. High-risk GDB commands are not permanently disabled; the first execution will return a warning, and the caller can run them by passing confirm=true upon retry.

Tool List

• gdb_session: Start, stop, restart, and status query for local GDB sessions

• gdb_load: Load local binaries, core files, symbol files, and startup arguments

• gdb_exec: General GDB CLI command execution entry point

• gdb_mi: Native GDB/MI command execution entry point

• gdb_remote: Configure and connect to the virtual machine's gdbserver

• gdb_context: View registers, stack, disassembly, call stack, breakpoints, memory maps, and shared libraries

• gdb_memory: Memory read, write, search, and dump

• gdb_register: Register read and write

• gdb_breakpoint: Normal breakpoints, hardware breakpoints, temporary breakpoints, and watchpoints

• gdb_run_control: Run, continue, step into, step over, instruction-level step, finish function, interrupt, kill program, and restart

• gdb_analyze: Crash and exploit feasibility analysis

• gdb_elf: Security checks (checksec), ELF headers, sections, segments, symbols, GOT/PLT, relocations, and strings

• gdb_pwndbg: Compatible execution of pwndbg/gef/peda commands

All tools return a unified JSON structure:

{
  "ok": true,
  "tool": "gdb_exec",
  "action": "exec",
  "risk_level": "low",
  "need_confirm": false,
  "executed_with_risk": false,
  "warning": null,
  "data": {},
  "stdout": "",
  "stderr": "",
  "raw": {},
  "error": null
}

Related MCP server: pwndbg-lldb-mcp

Installation

git clone https://github.com/traver88/gdb-mcp.git

The supported runtime environment for this project is Python 3.12.

Windows Environment: Codex + Windows gdb-mcp + Virtual Machine gdbserver

Install Python isolated environment in the project directory

python --version
python -m venv .venv
.\.venv\Scripts\activate
pip install -e .

Windows: Install GDB

Method A: MSYS2 MinGW64 GDB

1. Install MSYS2

2. Open MSYS2 MinGW64 terminal

3. Execute:

pacman -Syu  # 之后重启 MSYS2
pacman -S gdb gdb-multiarch

1. Add C:\msys64\mingw64\bin to Windows PATH

2. Verify:

gdb --version
gdb-multiarch --version

Run smoke_test

gdb-mcp项目目录下：
.\.venv\Scripts\activate
python tests\smoke_test.py

Success will output:

smoke test passed

smoke_test.py test content:

• Start Windows local GDB

• Load test program compiled from examples/hello.c

• Set breakpoint at main

• Run program

• Read registers

• Read stack

• Disassemble

• Close GDB

Virtual Machine (Ubuntu/Kali) Configuration

Install gdbserver

sudo apt update
sudo apt install -y gdbserver gdb gcc make binutils file

Start target program

cd xxx/xxx/
gdbserver 0.0.0.0:1234 ./pwn

Windows side connectivity test

powershell:

ping 192.168.56.101
Test-NetConnection 192.168.56.101 -Port 1234

Codex Configuration config.toml

[mcp_servers.gdb-mcp]
command = "D:\\gdb-mcp\\.venv\\Scripts\\python.exe"
args = ["D:\\gdb-mcp\\server.py"]

• command: Points to the Python program that starts the MCP server

• args: Points to the server.py server entry point

Codex Usage Example

Requirement example:

请使用 gdb-mcp：
- 启动 GDB
- 加载本地符号文件 E:/ctf/pwn/pwn
- 连接 192.168.56.101:1234 的 gdbserver
- 在 main 下断点
- continue
- 显示寄存器、栈、RIP 附近反汇编、backtrace

Equivalent MCP call:

gdb_session(action="start")
gdb_remote(
  action="connect",
  host="192.168.56.101",
  port=1234,
  mode="remote",
  local_binary="E:/ctf/pwn/pwn",
  confirm=true
)
gdb_breakpoint(action="add", location="main")
gdb_run_control(action="continue")
gdb_register(action="read_all")
gdb_memory(action="read", address="$rsp", size=160)
gdb_exec(command="x/20i $rip")
gdb_exec(command="bt")
gdb_context(depth=20)

Equivalent GDB command:

file "E:/ctf/pwn/pwn"
target remote 192.168.56.101:1234
b main
c
info registers
x/20gx $rsp
x/20i $rip
bt

Extended remote mode

Virtual machine:

gdbserver --multi 0.0.0.0:1234

MCP call:

gdb_remote(
  action="connect",
  host="192.168.56.101",
  port=1234,
  mode="extended-remote",
  local_binary="E:/ctf/pwn/pwn",
  remote_binary="/xxx/pwn",
  confirm=true
)
gdb_breakpoint(action="add", location="main")
gdb_run_control(action="run")
gdb_context(depth=20)

Internal GDB command:

file "E:/ctf/pwn/pwn"
set remote exec-file /xxx/pwn
target extended-remote 192.168.56.101:1234

FAQ

• Windows cannot ping the virtual machine: Check VM IP and network adapter mode

• Cannot connect to port 1234: Confirm gdbserver is running

• gdbserver only listening locally: Use gdbserver 0.0.0.0:1234 ./pwn

• Windows firewall blocking: Allow GDB or the corresponding port

• VM NAT mode inaccessible: Switch to Host-only/Bridged adapter or configure port forwarding

• local_binary and remote_binary confusion: The former is the Windows path, the latter is the Linux path

• Windows GDB cannot parse Linux ELF: Use a multi-architecture GDB for the corresponding architecture

• info proc mappings unavailable in remote mode: gdb_context will mark it as unavailable instead of crashing

• Missing remote libc symbols: Use gdb_remote(action="set_sysroot", ...) or set_solib_search_path

Risk Operation Confirmation

Examples of high-risk commands requiring confirmation:

• target remote HOST:PORT

• target extended-remote HOST:PORT

• disconnect

• detach

• set remote exec-file PATH

• set sysroot PATH

• set solib-search-path PATH

• shell ...

• source ...

• python ...

• dump memory ...

• restore ...

• maintenance ...

First call:

gdb_exec(command="target remote 192.168.56.101:1234")

Server returns need_confirm=true, retry with confirmation:

gdb_exec(command="target remote 192.168.56.101:1234", confirm=true)

After execution, the return contains executed_with_risk=true.