mcp server

gdb-mcp

traver88/gdb-mcpcommunitylistedunreviewed

Set up

Runs on your computer. Pick your agent and operating system.

Before you start

uv (`curl -LsSf https://astral.sh/uv/install.sh | sh`)

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "traver88-gdb-mcp": {
      "command": "uvx",
      "args": [
        "gdb-mcp"
      ]
    }
  }
}

same format Cursor, GitHub Copilot CLI, Junie, JetBrains AI Assistant, Augment (Auggie CLI), Factory Droid, Kiro, Devin CLI +12

Values in angle brackets are placeholders. Restart Claude Desktop after editing its config.Claude Desktop docs

README

synced Oct 23, 2026

gdb-mcp

gdb-mcp 是一个基于 MCP（Model Context Protocol） 的高权限 GDB 调试服务端，使用 pygdbmi 驱动本地 GDB，并将常见调试动作封装成结构化工具，适用于：

本地授权调试
CTF / Pwn 分析
Core Dump 分析
ELF 信息提取
远程 gdbserver 调试
崩溃现场排查
会话快照与自动化调试

项目当前面向 Python 3.12+。

1. 设计目标

这个项目的目标不是替代 GDB，而是提供一个适合模型和自动化系统调用的、有风险分级、可结构化返回、可远程调试、可渐进扩展 的 GDB 控制层。

核心特性：

基于 MCP 暴露调试工具
统一 JSON 返回格式
对高风险操作进行确认门控
支持本地与远程 gdbserver
支持只读模式
支持块级内存写入
支持会话快照与能力查询
支持原始 GDB CLI / MI 命令
支持崩溃分析、ELF 检查和 pwndbg 兼容命令

2. 当前项目结构

server.py             # MCP 聚合入口
server_runtime.py     # 共享运行时、控制器、公共 helper
tools_session.py      # 会话与加载工具
tools_memory.py       # 内存相关工具
tools_meta.py         # 快照与能力工具
tools_remote.py       # 远程调试与上下文工具
tools_control.py      # 寄存器、断点、运行控制工具
tools_advanced.py     # 原始命令、分析、ELF、插件兼容工具
gdb_controller.py     # GDB/MI 控制器
safety.py             # 风险评估规则
models.py             # 统一响应模型
config.py             # 环境变量配置
utils.py              # 解析与辅助函数
tests/                # unittest + smoke test
examples/             # 示例程序

3. 安装

3.1 克隆仓库

git clone <repo-url>
cd gdb-mcp

3.2 创建虚拟环境并安装

Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .

如果你要运行测试：

pip install -e .[dev]

3.3 安装 GDB

确保本机可执行：

gdb --version

Windows 下常见方案是使用 MSYS2：

pacman -Syu
pacman -S gdb gdb-multiarch

然后把 GDB 所在目录加入 PATH。

4. 启动方式

4.1 直接启动 MCP 服务

python server.py

或通过安装后的脚本：

gdb-mcp

4.2 在 MCP 客户端中配置

示例：

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

只要客户端支持 stdio MCP server，就可以用相同方式接入。

5. 环境变量配置

所有配置项都可以通过 GDB_MCP_ 前缀环境变量覆盖。

常用配置

变量	说明	默认值
`GDB_MCP_GDB_PATH`	GDB 可执行路径	`gdb`
`GDB_MCP_DEFAULT_TIMEOUT`	默认命令超时	`10`
`GDB_MCP_DEFAULT_REMOTE_TIMEOUT`	远程调试超时	`10`
`GDB_MCP_MAX_MEMORY_READ`	单次最大内存读取阈值	`4096`
`GDB_MCP_MAX_MEMORY_WRITE`	单次最大内存写入阈值	`4096`
`GDB_MCP_MAX_MEMORY_DUMP_WITHOUT_CONFIRM`	免确认 dump 阈值	`4096`
`GDB_MCP_MAX_STEP_COUNT`	最大步进数量	`1000`
`GDB_MCP_REMOTE_DEBUG_ENABLED`	是否启用远程调试	`true`
`GDB_MCP_ENABLE_RAW_GDB_EXEC`	是否启用原始 GDB CLI	`true`
`GDB_MCP_ENABLE_RAW_GDB_MI`	是否启用原始 GDB/MI	`true`
`GDB_MCP_ENABLE_PWNDBG_COMMANDS`	是否启用 pwndbg/gef/peda 兼容命令	`true`
`GDB_MCP_READ_ONLY_MODE`	是否启用只读模式	`false`
`GDB_MCP_BLOCK_MEMORY_WRITE_CHUNK_SIZE`	字节写入回退时的分块粒度	`256`
`GDB_MCP_DEFAULT_REMOTE_MODE`	默认远程模式	`remote`

只读模式

开启后，会阻止有状态修改类操作，例如：

gdb_memory(action="write")
gdb_memory(action="write_block")
gdb_register(action="write")
gdb_breakpoint(action="add")
gdb_run_control(action="run")

示例：

$env:GDB_MCP_READ_ONLY_MODE = "true"
python server.py

6. 统一返回格式

所有工具都返回统一 JSON：

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

字段说明：

ok：工具是否成功
tool：工具名
action：子动作名
risk_level：风险级别
need_confirm：是否需要再次以 confirm=true 执行
executed_with_risk：是否在确认后执行了风险操作
warning：风险说明
data：结构化结果
stdout / stderr：底层 GDB 输出
raw：原始记录
error：错误描述

7. 当前全部可用工具

7.1 会话与加载

`gdb_session`

用于管理 GDB 会话：

start
stop
restart
status

gdb_session(action="start")
gdb_session(action="status")

`gdb_load`

加载本地二进制、core 文件、符号文件和参数。

gdb_load(binary="E:/ctf/pwn/pwn", args=["a", "b"])

7.2 内存工具

`gdb_memory(action="read")`

gdb_memory(action="read", address="$rsp", size=128)

`gdb_memory(action="write")`

gdb_memory(action="write", address="0x404000", data_hex="41424344", confirm=True)

`gdb_memory(action="write_block")`

块级写入，优先走 restore ... binary：

gdb_memory(action="write_block", address="0x404000", data_hex="414243444546", confirm=True)

返回中会附带：

write_mode
executed_command
byte_count
partial_write_possible

`gdb_memory(action="search")`

gdb_memory(action="search", address="$rsp", size=256, pattern="41414141")

`gdb_memory(action="dump")`

gdb_memory(action="dump", address="0x404000", size=512, confirm=True)

7.3 元工具

`gdb_snapshot`

支持：

show
save
list
restore

gdb_snapshot(action="save", name="crash_case_1")
gdb_snapshot(action="list")
gdb_snapshot(action="restore", name="crash_case_1")

当前行为：

将快照保存到工作目录下的 .gdb-mcp-snapshots/
保存当前 binary / core / symbol_file / 远程状态 / 最近命令 / inferior 状态
恢复时会优先尝试重新加载 binary、sysroot、solib 路径和远程配置，再回填缓存状态
恢复结果里会返回 restore.operations，展示每个阶段是否执行成功
可用于判断当前是“完全恢复”“部分恢复”还是“仅缓存恢复”

`gdb_capabilities`

gdb_capabilities()

返回内容包括：

原始 GDB CLI 是否启用
原始 GDB/MI 是否启用
pwndbg 命令是否启用
远程调试是否启用
是否只读模式

7.4 远程调试与上下文

`gdb_remote`

支持：

status
connect
disconnect
reconnect
setup
set_sysroot
set_solib_search_path
set_remote_exec_file
set_debug_file_directory

远程连接示例：

gdb_remote(
  action="connect",
  host="192.168.56.101",
  port=1234,
  mode="remote",
  local_binary="E:/ctf/pwn/pwn",
  confirm=True
)

扩展远程示例：

gdb_remote(
  action="connect",
  host="192.168.56.101",
  port=1234,
  mode="extended-remote",
  local_binary="E:/ctf/pwn/pwn",
  remote_binary="/home/user/pwn",
  confirm=True
)

`gdb_context`

寄存器
当前指令
附近反汇编
栈内容
backtrace
breakpoints
mappings
shared libraries
线程与 frame 信息
函数参数推断

gdb_context(depth=20)

7.5 寄存器、断点、执行控制

`gdb_register`

支持：

read_all
read
write

gdb_register(action="read", name="rip")
gdb_register(action="write", name="rip", value="0x401000", confirm=True)

`gdb_breakpoint`

支持：

list
add
delete
enable
disable
condition
clear
watch
rwatch
awatch

gdb_breakpoint(action="add", location="main")
gdb_breakpoint(action="list")

`gdb_run_control`

支持：

run
continue
step
next
stepi
nexti
finish
until
interrupt
kill
restart

gdb_run_control(action="continue")
gdb_run_control(action="step", count=3)

7.6 原始命令、分析、ELF、插件兼容

`gdb_exec`

执行原始 GDB CLI 命令：

gdb_exec(command="info registers")
gdb_exec(command="x/10i $rip")

`gdb_mi`

执行原始 GDB/MI 命令：

gdb_mi(mi_command="-thread-info")

`gdb_analyze`

做崩溃和可利用性线索分析：

gdb_analyze(mode="crash")

当前会输出：

signal 推断
fault address
PC 是否疑似可控
栈中是否出现明显填充值
backtrace 摘要
参数寄存器摘要
possible causes
exploitation_hints.leak_hints
exploitation_hints.rop_gadget_hints
exploitation_hints.libc_base_guess
exploitation_hints.leak_chain_suggestions
exploitation_hints.strategy_hints

这部分结果现在会尝试给出：

栈上疑似 libc / PIE 地址
当前窗口中的 gadget 分类线索，如 ret、pop_rdi、syscall
基于泄露地址的 libc 基址粗略猜测
常见泄露链和 ret2libc/ROP 方向提示
基于崩溃类型的简单利用路径建议

`gdb_elf`

支持：

checksec
info
entry
sections
segments
symbols
relocations
dynamic
got
plt
strings
rop
leaks

gdb_elf(action="checksec", path="E:/ctf/pwn/pwn")
gdb_elf(action="rop", path="E:/ctf/pwn/pwn")
gdb_elf(action="leaks", path="E:/ctf/pwn/pwn")

新增辅助内容：

rop：从反汇编结果里提取 gadget，并附带 category
got / plt：附带结构化条目解析
leaks：返回常见 libc / 输出函数候选，以及常见泄露链建议
更适合与 checksec、gdb_analyze 联动使用

8. 典型使用流程

本地调试

gdb_session(action="start")
gdb_load(binary="E:/ctf/pwn/pwn")
gdb_breakpoint(action="add", location="main")
gdb_run_control(action="run")
gdb_context(depth=20)

远程 gdbserver 调试

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_context(depth=20)

打补丁

gdb_memory(action="write_block", address="0x404000", data_hex="90909090", confirm=True)

崩溃分析

gdb_context(depth=32)
gdb_analyze(mode="crash")
gdb_elf(action="checksec")

9. 远程调试典型架构

MCP Client
-> gdb-mcp
-> local GDB
-> target remote / extended-remote
-> remote gdbserver
-> target process

Linux 目标机安装：

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

启动：

gdbserver 0.0.0.0:1234 ./pwn

Windows 侧检查连通性：

Test-NetConnection 192.168.56.101 -Port 1234

10. 风险控制模型

项目不是“一刀切禁止高危命令”，而是使用 风险分级 + 二次确认：

low：直接执行
medium / high / critical：第一次返回警告
再次调用时传 confirm=true 才会执行

典型受控动作：

target remote
shell
python
内存写入
dump memory
寄存器写入
kill / restart

11. 测试与验证

11.1 smoke test

python tests/smoke_test.py

11.2 单元测试

python -m unittest tests.test_utils tests.test_gdb_controller tests.test_server_helpers tests.test_meta_tools tests.test_remote_tools tests.test_control_tools tests.test_advanced_tools

11.3 语法检查

python -m compileall server.py server_runtime.py tools_session.py tools_memory.py tools_meta.py tools_remote.py tools_control.py tools_advanced.py gdb_controller.py utils.py tests

12. 已知限制

write_block 目前要求数值地址，不支持复杂 GDB 表达式地址。
块级写入依赖本地临时二进制文件与 GDB restore 命令。
某些远程场景下 info proc mappings 可能不可用，这会体现在结构化结果里，而不是导致整个工具失败。
gdb_analyze 目前是启发式分析，不是严格 exploitability engine。
gdb_pwndbg 是否真正可用，取决于本机 GDB 环境是否已安装相应插件。

13. 许可证

MIT