gdb-mcp

面向二进制安全研究(逆向工程 / PWN)的 GDB MCP 服务器,对 pwndbg 插件的额外功能做了一等公民适配:堆分析、cyclic 模式、checksec、ROP gadget、内存映射、telescope 等。

架构

MCP 客户端 (Kimi Code / Claude Desktop,可运行在 Windows)
   │  stdio(可经 wsl.exe / ssh 桥接)
   ▼
gdb-mcp 服务器(Python,运行在带 gdb+pwndbg 的 Linux/WSL 主机)
   │  pygdbmi(GDB/MI 机器接口)
   ▼
gdb --interpreter=mi2(pwndbg 经 ~/.gdbinit 自动加载)

• 断点、栈帧、寄存器、内存读写等走 GDB/MI,返回结构化 JSON;

• pwndbg 命令经 interpreter-exec console 透传执行,输出统一剥 ANSI 转义、截断后返回文本;

• 未封装的任意 gdb/pwndbg 命令都可经 gdb_command 逃生舱执行。

环境要求

服务器端(调试主机)需要:

• Linux(pwndbg 仅支持 Linux;WSL2 亦可)

• gdb、gcc(仅测试需要)

• pwndbg(已执行过 setup.sh,即 ~/.gdbinit 会加载它)

• Python ≥ 3.10

安装(以 WSL2 kali 为例)

# 在 WSL 内执行;项目目录可放在 Windows 侧,经 /mnt/c 访问
uv venv ~/venv/gdb-mcp
uv pip install --python ~/venv/gdb-mcp/bin/python -e '/mnt/c/Users/<你>/Desktop/Develop/gdb-mcp[dev]'

# 或不用 uv:
python3 -m venv ~/venv/gdb-mcp
~/venv/gdb-mcp/bin/pip install -e '/mnt/c/Users/<你>/Desktop/Develop/gdb-mcp[dev]'

若 pwndbg 不在默认位置,可用环境变量 GDB_MCP_PWNDBG_INIT 指向其 gdbinit.py。

MCP 客户端配置

Kimi Code(Windows 客户端 → WSL 内服务器)

编辑 ~/.kimi-code/mcp.json(用户级)或项目级 .kimi-code/mcp.json:

{
  "mcpServers": {
    "gdb": {
      "command": "wsl.exe",
      "args": ["-d", "kali-linux", "-e", "/root/venv/gdb-mcp/bin/python", "-m", "gdb_mcp"],
      "startupTimeoutMs": 60000
    }
  }
}

在 TUI 里也可用 /mcp-config 交互式添加,/mcp 查看连接状态。

Claude Desktop

claude_desktop_config.json 中同样加上上面的 gdb 条目(同一 JSON 结构)。

原生 Linux(客户端与调试同机)

{
  "mcpServers": {
    "gdb": {
      "command": "/root/venv/gdb-mcp/bin/python",
      "args": ["-m", "gdb_mcp"]
    }
  }
}

配合 pwntools 调试(替代 gdb.attach)

先区分两个容易混淆的概念:

• pwntools 的 gdb.attach(p):由 pwntools 拉起的独立 GDB 进程,与本 MCP 服务器无关;

• 本服务器的 gdb_attach:MCP 内部 GDB 会话对目标进程做 ptrace attach。

同一进程只允许一个 ptrace tracer,二者不能对同一进程同时使用。要让 AI 调试 pwntools 脚本拉起的进程,推荐脚本打印 PID 并暂停,由本服务器 attach:

from pwn import *

p = process('./vuln')
log.info(f'target pid: {p.pid}')
pause()          # 等待调试器 attach + 下好断点;回车后继续发送 payload
p.sendline(payload)
p.interactive()

AI 侧对话流程:

1. gdb_attach(target="./vuln", wait=30) —— 按进程名 attach;脚本还没拉起进程时会等待其出现。也可先 gdb_find_process("./vuln") 找到 PID,再 gdb_attach(target="<pid>")。

2. gdb_breakpoint_set(location="vuln") 等下断。

3. gdb_continue() —— 目标通常正阻塞在 read() 等待输入,continue 让它回到等待状态。

4. 回到 pwntools 脚本按回车发出 payload,断点命中,随后用 pwndbg_context、pwndbg_telescope、pwndbg_heap 等分析。

注意事项:

• 不要对同一进程同时使用 pwntools 的 gdb.attach() 和本服务器 —— 只能有一个 tracer。

• gdb_quit 对 attach 的进程是 detach 而非 kill,进程继续运行,pwntools 脚本恢复控制。

• attach 非子进程受 kernel.yama.ptrace_scope 限制:非 root 且值为 1 时会被拒绝,工具会返回修复提示(echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope)。

• pwntools 脚本必须和本 MCP 服务器跑在同一个 WSL 发行版(共享 /proc);gdb_find_process 找不到进程,通常是进程已退出(僵尸进程 cmdline 为空,会按 comm 匹配并标记 zombie)或跨了发行版/容器。

• 想从程序起点开始调试:改用 gdbserver :1234 ./vuln 起目标,然后 gdb_start(mode="remote", target="localhost:1234", file="./vuln")。

交互式程序(stdin/stdout 对话)

菜单式 CTF 题的典型痛点:程序跑起来后阻塞在 read() 等输入。gdb_start 默认给 inferior 分配一个 pty(pty=true,仅 local 模式),配合两个工具完成对话:

1. gdb_run(timeout=10) —— 程序显示菜单后阻塞,工具返回 "still running" 属正常。

2. gdb_recv() —— 读出菜单文本/提示符。

3. gdb_send_stdin(data="1") —— 发送菜单选项(自动补换行;二进制 payload 用 hex=true,如 data="41424300")。

4. 重复 2-3 推进到漏洞点;若已下断点,gdb_continue 会在命中时返回停止信息。

5. 卡死时 gdb_interrupt() 中断(MI 中断 + SIGINT 兜底)。

pty 同时解决了 stdin 重定向导致的 stdio 全缓冲问题(程序以为自己在终端里跑)。attach/remote 模式没有 pty —— 那时 stdin 归拉起进程的一方(pwntools 脚本)所有。

gdb_recv 直接读 inferior 的 pty,输出只有程序自己的文本,不会混入 pwndbg context 或 GDB 日志。gdb_run/gdb_continue 结果里附带的 context 可用 with_context=false 关闭;pwndbg 每次停止时的自动 context 显示可用 gdb_command("set context-output /dev/null") 彻底静音。

环境变量

工具清单(39 个)

会话与执行控制

检查与修改

pwndbg 封装

其余 pwndbg 功能(got、plt、canary、sigreturn、fmtarg、onegadget……)直接通过 gdb_command 调用。

测试与验证

在调试主机(WSL/Linux)上:

cd /mnt/c/Users/<你>/Desktop/Develop/gdb-mcp
~/venv/gdb-mcp/bin/python -m pytest -q          # 单元 + 集成测试(真实 gdb+pwndbg)
~/venv/gdb-mcp/bin/python scripts/smoke_client.py /tmp/crackme ~/venv/gdb-mcp/bin/python

scripts/smoke_client.py 会以 MCP 客户端身份走一遍 stdio 协议:列出工具 → 启动会话 → checksec → 下断点 main → run → telescope → cyclic 生成/定位 → 退出。

安全警告

本服务器等价于暴露任意命令执行:gdb 内的 shell、python 命令以及 inferior 本身都可执行任意代码。仅供本机 stdio 使用,不要把它包装成网络服务暴露出去,也不要对不可信的目标二进制无防护地使用。

项目结构

src/gdb_mcp/
├── server.py        # FastMCP 入口与工具注册
├── session.py       # GdbSession:pygdbmi 封装、生命周期、console 执行、*stopped 收集
├── util.py          # ANSI 剥离、截断、异常包装
└── tools/
    ├── core.py      # 会话/执行控制/断点/观察点/栈/寄存器/内存/反汇编/求值/透传
    └── pwndbg.py    # pwndbg 专用封装
tests/               # pytest:单元测试 + 真实 gdb+pwndbg 集成测试
scripts/smoke_client.py  # MCP 协议冒烟客户端