pygdbmi-mcp-server
English | 中文
这是一个基于 pygdbmi 开发的 MCP (Model Context Protocol) 服务器，旨在通过 MCP 协议调用 GDB 进行动态调试。
本项目部分代码参考自 pwnomcp。
功能特性
本服务器提供了一系列 MCP 工具，用于与 GDB 进行交互：
| 分类 | 工具 | 说明 |
|---|---|---|
| 调试控制 | execute | 执行任意 GDB/pwndbg 命令。 |
| 调试控制 | run | 运行加载的二进制文件。 |
| 调试控制 | interrupt | 中断正在运行的程序。 |
| 调试控制 | finish | 运行直到当前函数返回。 |
| 调试控制 | step_control | 执行步进命令 (continue, next, step, nexti, stepi)。 |
| 远程调试 | target_remote | 连接到远程调试目标 (如 gdbserver)。 |
| 远程调试 | disconnect | 断开远程连接。 |
| 文件与会话管理 | set_file | 加载用于调试的二进制文件。 |
| 文件与会话管理 | set_poc_file | 设置 PoC 文件 (通过 set args 传递给二进制文件)。 |
| 文件与会话管理 | get_session_info | 获取当前调试会话信息。 |
| 断点管理 | set_breakpoint | 在指定位置设置断点。 |
| 断点管理 | list_breakpoints | 列出所有断点。 |
| 断点管理 | delete_breakpoint | 按编号删除断点。 |
| 断点管理 | toggle_breakpoint | 切换断点的启用/禁用状态。 |
| 状态检查 | get_context | 获取调试上下文 (寄存器, 堆栈, 反汇编, 代码, 回溯)。 |
| 状态检查 | get_memory | 读取指定地址的内存。 |
| 状态检查 | disassemble | 反汇编指定地址。 |
安装与使用
1. 克隆仓库
git clone https://github.com/cnitlrt/pygdbmi-mcp-server
cd pygdbmi-mcp-server2. 配置环境
在项目根目录下创建或修改 .env 文件，配置服务器监听地址和传输模式：
PORT=1111
HOST="0.0.0.0"
# TRANSPORT 可选 "streamable-http" (SSE/HTTP) 或 "stdio" (标准输入输出)
# 若未设置，服务器会在非交互式 stdin（例如 Codex MCP）下自动选择 stdio
TRANSPORT="streamable-http"可选调试器配置：
# 调试器可执行文件路径或命令名
# Windows 一般使用 gdb.exe，Linux/macOS 可使用 pwndbg 或 gdb
GDB_PATH="gdb"3. 安装依赖
本项目推荐使用 uv 进行依赖管理和环境配置。
# 创建虚拟环境 (建议使用 Python 3.13 或更高版本)
uv venv --python 3.13
# 激活虚拟环境 (Linux/macOS)
source .venv/bin/activate
# Windows
# .venv\Scripts\activate
# 安装项目及其依赖
uv pip install -e .4. 运行服务器
uv run pygdbmi-mcp-server也可以通过参数指定传输模式：
uv run pygdbmi-mcp-server --transport streamable-http
uv run pygdbmi-mcp-server --transport stdioWindows 说明
- 在 Windows 上，服务默认使用
gdb（不再默认依赖pwndbg）。 - 若
pwndbg专有命令不可用，get_context会自动降级为标准 GDB 命令。 get_memory已改为标准 GDBx/...输出，无需pwndbg也可使用。
远程连接（SSE/HTTP）
让服务器监听公网/局域网地址并使用 streamable-http:
uv run pygdbmi-mcp-server --transport streamable-http --host 0.0.0.0 --port 1111默认 SSE 端点为 /mcp，因此远程地址通常是：
http://:1111/mcp配置
codex
[mcp_servers.gdb]
url = "http://127.0.0.1:1111/mcp"antigravity
{
"mcpServers": {
"gdb": {
"serverUrl": "http://127.0.0.1:1111/mcp/",
"disabled": false
}
}
}mcp-server
{
"servers": {
"gdb-mcp-server": {
"url": "http://127.0.0.1:1111/mcp",
"type": "streamable-http"
}
},
"inputs": []
}5. 远程调试示例
使用 target_remote 连接到 gdbserver 进行远程调试：
# 在远程机器或另一个终端启动 gdbserver
gdbserver localhost:1234 /path/to/binary
# 通过 MCP 工具进行调试：
# 1. 使用 set_file 加载符号文件（与远程二进制相同）
# 2. 使用 target_remote 连接到 gdbserver
# 示例: target_remote("localhost:1234")
# 3. 使用 set_breakpoint 设置断点
# 4. 使用 step_control("continue") 继续执行
# 5. 使用 disconnect 断开连接远程调试特别适用于：
- 嵌入式系统调试
- 内核模块调试
- 跨平台调试
- Docker 容器内程序调试