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-server

2. 配置环境

在项目根目录下创建或修改 .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 stdio

Windows 说明

• 在 Windows 上，服务默认使用 gdb（不再默认依赖 pwndbg）。
• 若 pwndbg 专有命令不可用，get_context 会自动降级为标准 GDB 命令。
• get_memory 已改为标准 GDB x/... 输出，无需 pwndbg 也可使用。

远程连接（SSE/HTTP）

让服务器监听公网/局域网地址并使用 streamable-http:

uv run pygdbmi-mcp-server --transport streamable-http --host 0.0.0.0 --port 1111

默认 SSE 端点为 /mcp，因此远程地址通常是：

http://<server-ip>: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 容器内程序调试