pwndbg-mcp

通过标准 HTTP MCP 协议让 AI Agent 控制 pwndbg，支持 Agent 全自动无界面调试和用户终端协作调试。

架构

Agent ── MCP/HTTP ──> Gateway :22334
                           ├── managed/headless pwndbg ──> 127.0.0.1:动态端口
                           └── attached/collaborative pwndbg ──> 127.0.0.1:动态端口

• Gateway 是始终运行、对 Agent 暴露全部工具的 MCP Server。

• debug_session_start 自动启动的 managed session 固定为 headless。

• 用户手动启动的 pwndbg 自动注册为 attached/collaborative session，保留完整 context、命令回显和人工输入能力。

• pwndbg 插件仅作为内部后端，使用回环动态端口；managed 后端使用独立随机 Bearer token。

• 全部 gdb_* 工具作用于 Gateway 默认会话，无需传递 session_id。

Related MCP server: pwndbg-lldb-mcp

要求

• Python 3.10+

• PATH 中存在独立的 pwndbg 启动器

• Linux；自动服务安装需要 systemd user service

项目不会通过系统 /usr/bin/gdb 检测 pwndbg，因为独立安装的 pwndbg 带有自己的 GDB 和 Python 运行环境。

安装

运行交互式设置，将插件 loader 加入 ~/.gdbinit：

python3 setup.py

也可以手动添加：

source /absolute/path/to/pwndbg-mcp/pwndbg_mcp.py

安装并启动 Gateway 服务

仅本机访问：

python3 setup.py --install-service

允许远程客户端连接：

python3 setup.py --install-service --gateway-host 0.0.0.0 --gateway-port 22334

安装脚本会生成 ~/.config/systemd/user/pwndbg-mcp-gateway.service，校验 unit，执行 daemon-reload、enable 和 restart，最后确认服务为 active。重复执行会立即应用新的 host、port、Python 路径和项目路径。

服务管理：

systemctl --user status pwndbg-mcp-gateway
systemctl --user restart pwndbg-mcp-gateway
journalctl --user -u pwndbg-mcp-gateway -f

不使用 systemd 时可以前台启动：

python3 -m gateway.server --host 127.0.0.1 --port 22334

MCP 客户端配置

本机客户端：

{
  "mcpServers": {
    "pwndbg-mcp": {
      "url": "http://127.0.0.1:22334/mcp"
    }
  }
}

远程客户端应将 127.0.0.1 替换为 Gateway 主机的实际 IP。

使用方式

Agent 全自动调试

创建 managed/headless session：

{
  "name": "debug_session_start",
  "arguments": {
    "program": "/absolute/path/to/program",
    "cwd": "/optional/working/directory",
    "environment": {
      "LD_LIBRARY_PATH": "/optional/library/path"
    }
  }
}

debug_session_start 不接受 mode；Gateway 启动的会话永远为 headless。创建成功后自动成为默认会话，后续直接调用 gdb_run、gdb_read_output、gdb_write_input 等工具。

用户协作调试

pwndbg ./program

插件会启动回环后端并向 Gateway 注册 attached/collaborative session。Gateway 暂时不可用时会自动重试。Agent 操作会在用户终端显示为正常 pwndbg 命令：

pwndbg> break main
Breakpoint 1 ...
pwndbg> run
Starting program: ...
...
[ REGISTERS ] [ DISASM ] [ STACK ] [ BACKTRACE ]
pwndbg>

命令回显只写入控制台，不进入 inferior stdin，不会被 read、fgets、gets 或 scanf 读取。

多会话与默认会话

debug_session_list    列出会话及 default_session_id
debug_session_select  切换默认会话
debug_session_get     查看指定会话
debug_session_stop    停止 managed session 或分离 attached session

managed session 创建后自动成为默认。新 attached session 仅在当前没有默认会话时成为默认。默认会话退出或断开后，Gateway 自动选择剩余最新的 ready session。

调试工具

批量断点支持普通、地址、临时、硬件、条件和禁用断点，并可在失败时回滚。裸十六进制地址会自动转换为 GDB 的 *0x... 地址语法。

运行工具返回 execution_id。Agent 可使用游标增量读取带 stream 类型的输出；每个 execution 最多保留 8 MiB，并在旧 cursor 失效时返回 cursor_expired。

插件内管理命令

mcp-status                    查看后端地址、模式和当前 execution
mcp-mode collaborative       切换到终端协作输出
mcp-mode headless            切换到无界面输出（inferior 运行时禁止切换）
mcp-stop                     停止当前 pwndbg 内部后端

通常不需要手动改变插件后端地址；Gateway 使用动态端口完成注册和路由。

安全

• 插件后端只监听 127.0.0.1。

• Gateway /internal/register 只接受回环连接。

• managed 后端使用每会话随机 token。

• Gateway 当前未实现客户端认证。监听 0.0.0.0 时必须使用防火墙、可信网络或反向代理认证限制 22334 端口。

故障排查

检查 Gateway：

systemctl --user status pwndbg-mcp-gateway
journalctl --user -u pwndbg-mcp-gateway -n 100 --no-pager
ss -ltnp 'sport = :22334'

检查 MCP 初始化：

curl -X POST http://127.0.0.1:22334/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}'

检查手动 pwndbg 后端：

pwndbg> mcp-status

开发与测试

共享工具 schema 位于 pwndbg_plugin/tool_schema.py；Gateway 在 schema 上增加会话管理工具，插件负责 GDB 主线程内的实际执行。

python3 -m unittest discover -s tests -v
python3 -m compileall -q gateway pwndbg_plugin tests

示例程序包含 stdin 读取路径，用于验证 headless PTY：

cd examples
./compile.sh
pwndbg ./test_program

License

MIT