How do I use gdb-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@gdb-mcp debug remote binary with breakpoint at main" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

de en es ja ko ru zh

gdb-mcp

by traver88

Overview Schema Related Servers Score Discussions

Python

Local

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

Install Server

license - permissive license

quality

maintenance

How are these scores calculated?

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

Latest Blog Posts

Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
open source
OpenAI
Tool Definition Quality Score (TDQS)
By punkpeye on April 3, 2026.
mcp
The Hackers Who Tracked My Sleep Cycle
By punkpeye on March 26, 2026.
security

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/traver88/gdb-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server