xdbg-mcp

基于 x64dbg_automate 的 x64dbg/x32dbg/x96dbg MCP 服务端，面向 CTF 逆向与日常动态分析。

这次升级了什么

本次版本重点增强了实战稳定性：

1. run_to / wait_until_stopped 增加停下原因诊断

• 可返回 stop_reason、stop_event、当前 instruction_pointer
• run_to 不再“只要停下就算到达”，会校验是否真的命中目标地址

2. 自动重连后恢复断点

• MCP 记录通过工具下的软/硬件/内存断点
• 会话瞬断后自动重连时会尝试恢复断点
• health 可查看断点跟踪数量和重连计数

3. 新增事件队列工具

• get_latest_event
• drain_events
• wait_for_event

4. 新增 CTF 输入卡住绕过工具

• write_text_memory
• inject_string_and_continue

适用场景：程序卡在 scanf/read/fgets 时，直接写入目标缓冲区并把 EIP/RIP 跳到调用后。

支持客户端

已支持以下 MCP 客户端（stdio 启动方式）：

1. Cursor
2. Claude Desktop
3. Cline
4. Roo Code
5. Cherry Studio
6. Codex

完整部署（Windows）

1. 前置依赖

1. Python 3.11+
2. Git
3. x64dbg（含 x32dbg.exe / x64dbg.exe / x96dbg.exe）

建议统一目录示例：

D:\tools\x64dbg\release\x96dbg.exe

2. 安装 x64dbg-automate 插件文件

从官方 Releases 下载下面 3 个文件：

• x64dbg-automate.dp32
• x64dbg-automate.dp64
• libzmq-mt-4_3_5.dll

下载地址：

• https://github.com/dariushoule/x64dbg-automate/releases

把这 3 个文件放到你实际使用的调试器插件目录（常见二选一）：

<X64DBG_DIR>\plugins\

<X64DBG_DIR>\x32\plugins\
<X64DBG_DIR>\x64\plugins\

3. 安装本项目

git clone https://github.com/utmost3/xdbg-mcp.git
cd xdbg-mcp
python -m pip install -U pip
python -m pip install -e .

4. 启动 MCP 服务

python -m xdbg_mcp --xdbg-path D:\tools\x64dbg\release\x96dbg.exe

或：

set XDBG_PATH=D:\tools\x64dbg\release\x96dbg.exe
xdbg-mcp

5. MCP 客户端配置示例

{
  "mcpServers": {
    "xdbg": {
      "command": "python",
      "args": [
        "-m",
        "xdbg_mcp",
        "--xdbg-path",
        "D:\\tools\\x64dbg\\release\\x96dbg.exe"
      ]
    }
  }
}

仓库示例文件：mcp.client.json.example

常用工具

• 会话：health list_sessions start_session connect_session disconnect terminate_session
• 执行：go pause step_into step_over step_trace run_to run_until_expr
• 等待：wait_until_running wait_until_stopped
• 观察：snapshot_context get_register(s) read_memory disassemble
• 断点：set/clear/list_breakpoint set/clear_hardware_breakpoint set/clear_memory_breakpoint
• 内存：write_memory_hex write_text_memory find_memory_pattern
• 事件：get_latest_event drain_events wait_for_event
• 输入绕过：inject_string_and_continue

CTF 卡输入快速处理

假设当前停在 scanf 调用前后，且输入缓冲区地址是 ebp-0x96，调用返回后地址是 0x40179E：

1. 直接写入候选字符串

{
  "buffer_address": "ebp-0x96",
  "text": "flag{...}",
  "continue_at": "0x40179E",
  "encoding": "ascii",
  "append_null": true
}

调用工具：inject_string_and_continue

2. 再用 run_to / wait_until_stopped(detailed=true) 看是否命中校验分支

环境变量

• XDBG_MCP_AUTO_RECONNECT=1|0：是否启用自动重连（默认 1）
• XDBG_MCP_RETRY_ATTEMPTS=<int>：瞬时错误重试次数（默认 2）
• XDBG_MCP_WAIT_POLL_MS=<int>：等待轮询间隔毫秒（默认 100）
• XDBG_MCP_EVENT_DRAIN_LIMIT=<int>：单次事件拉取上限（默认 64）
• XDBG_MCP_SKIP_PLUGIN_CHECK=1|0：跳过插件依赖检查（默认 0）

常见问题

1. Missing x64dbg automate plugin dependencies

• 原因：插件文件不在实际生效的 plugins 目录
• 处理：把 3 个文件放到报错提示目录

2. run_to 未到达目标

• 先看返回里的 reached、stop_reason、instruction_pointer
• 若是命中其他断点，可清理后重试

3. wait_until_stopped 超时

• 可用 pause_on_timeout=true
• 或用 inject_string_and_continue 跳过阻塞输入调用

CTF 工作流文档

• CTF 逆向实战指南（中文）