内容
# x64dbg MCP 服务器插件（远程版）
English | [中文](docs/README_CN.md)
一个适用于 x64dbg 和 x32dbg 的模型上下文协议（MCP）服务器实现，通过 JSON-RPC 2.0 接口启用远程调试。该插件允许外部应用程序和 AI 代理以编程方式与调试器交互。
**现在支持 x64 和 x86 架构！**
> **分支说明**：这是 [SetsunaYukiOvO/x64dbg-mcp](https://github.com/SetsunaYukiOvO/x64dbg-mcp) 的定制化分支，包含以下修改：
> - 默认监听地址更改为 `0.0.0.0` 以便远程访问
> - 为 LAN/远程使用禁用源/主机验证和速率限制
> - 为所有源启用 CORS 头
> - 默认启用所有权限
> - 本地捆绑 nlohmann/json（无需 vcpkg 依赖）
## 功能
- **完全符合 MCP 规范**：实现所有三个核心 MCP 模块
- **工具（79）**：AI 可调用的调试功能
- **资源（7 + 8 个模板）**：应用程序控制的上下文数据源
- **提示（10）**：用户引导的调试工作流模板
- **JSON-RPC 2.0 协议**：标准、语言无关的接口
- **可流式传输的 HTTP 传输**（MCP 2025-03-26）在 `/mcp` 上，以及旧版 HTTP + SSE 在 `/sse` 上用于旧客户端
- **工具 - AI 控制的调试（79 个功能）**：
- 执行控制（init/run/pause/step/run_to/restart/stop）
- 内存读取/写入/搜索/分配
- 寄存器访问（50+ 个寄存器，包括 GPR、SSE、AVX）
- 断点管理（软件、硬件、内存、条件、日志）
- 反汇编和符号解析
- 线程管理（列表、切换、挂起、恢复）
- 堆栈跟踪和分析
- **转储和分析**（模块转储、内存转储、打包检测、OEP 检测）
- **脚本执行**（执行 x64dbg 命令、批处理操作）
- **上下文快照**（捕获和比较调试状态）
- **资源 - 上下文提供者（7 个直接 + 8 个模板）**：
- 直接资源：调试器状态、寄存器、模块、线程、内存映射、断点、堆栈
- 资源模板：内存内容、反汇编、模块信息、符号解析、函数分析
- 只读、应用程序控制的访问
- **提示 - 工作流模板（10 个提示）**：
- 崩溃分析、漏洞挖掘、函数跟踪
- 二进制解包、算法逆向、执行比较
- 字符串搜索、代码修补、API 监控
- 调试会话初始化
- **安全**：基于权限的访问控制
- **可扩展**：自定义方法、资源和提示的插件架构
## 版本 1.0.8 中的新功能
- **安全强化**：添加 CORS 源/主机头验证，以防止针对 HTTP 服务器的 CSRF 和 DNS 重新绑定攻击。现在，所有 POST 端点都需要一个有效的 `源`（如果存在）来匹配配置的源允许列表，并且 `主机` 头必须解析为环回地址。脚本执行、内存写入和寄存器写入现在**默认禁用**（严格选择加入）。从 POST 响应中删除 `Access-Control-Allow-Origin: *`。
- **速率限制**：POST 端点现在限速为 100 请求/秒，以防止 DoS 攻击。
- **SSE 缓冲区强化**：SSE 客户端累积缓冲区上限为 1 MiB，以防止内存耗尽。
- **路径遍历保护**：`dump.module` 和 `dump.memory_region` 现在验证 `output_path` 以拒绝 `..`、UNC 路径和空字节。
- **命令注入保护**：`debug.init` 现在拒绝包含逗号的路径/参数/目录参数，以防止 x64dbg 命令参数混淆。
## 旧版本
### 版本 1.0.7
- **流式 HTTP 传输（MCP 2025-03-26）**：新的统一 `/mcp` 端点，支持 POST/GET/DELETE。
- **HTTP + SSE 传输规范合规性修复**：`GET /sse` 现在发送所需的 `event: endpoint` 握手；`POST /message` 现在正确确认。
- **内存读取/搜索不再需要暂停调试目标**（#8）。
### 版本 1.0.6
- **新工具**：`debug_init` - 通过加载可执行文件启动新的调试会话（等效于 x64dbg 的“运行”按钮）。即使没有活动会话，也可以使用，因此机器人可以在目标崩溃/退出后重新启动而无需重新连接。可选接受 `path`、`arguments` 和 `current_dir`；如果省略 `path`，则重用最近观察到的调试目标路径。
- `debug_restart` 不再需要活动调试会话 - 现在回退到缓存的调试目标路径，因此可以在目标退出或崩溃后恢复会话。
### 版本 1.0.5
- **错误修复**：`debug_restart` 现在正确工作 - x64dbg 没有 `restart` 脚本命令；该工具现在使用 `init "<path>"` 来镜像 GUI 的重启行为（PR #5 by @AMRICHASFUCK）
- **文档修复**：资源数量更正为“7 直接 + 8 模板”（错误地列为 15）
### 版本 1.0.4
- 12 个新工具（66 → 78）：`eval_expression`、`xref_get`、`function_list`/`function_get`、`module_get_exports`/`module_get_imports`、`assembler_assemble`、`bookmark_set`/`delete`/`list`、`patch_list`/`patch_restore`
- 地址解析：所有地址参数通过 DbgEval 接受符号、寄存器和 x64dbg 表达式
- `memory_search` 连续十六进制格式支持
- Claude Code 插件（`skills/`）带有 11 个 RE 斜杠命令
- 所有 10 个 MCP 提示重写为结构化多阶段工作流
- 转储：修复 ImageBase，删除不可靠的自动解包/IAT 重建存根
### 版本 1.0.3
- 概括解包逻辑、解包/转储稳定性修复、运行状态恢复
### 版本 1.0.2
- 自动化测试关键错误修复、构建系统改进
### 版本 1.0.1
- 线程和堆栈管理 API
- 增强的错误处理和日志记录
有关完整的版本历史，请参阅 [CHANGELOG.md](CHANGELOG.md)
## 从源代码构建
### 先决条件
- **Windows 10/11**（x64）
- **CMake** 3.15 或更高版本
- **Visual Studio 2022**，带有 C++ 桌面开发工作负载
- **Git** - 用于克隆存储库
> **注意**：无需 vcpkg。nlohmann/json 捆绑在 `third_party/` 中。
### 快速构建
```powershell
# 克隆存储库
git clone https://github.com/HollyZoe/x64dbg-mcp.git
cd x64dbg-mcp
# 配置（无需 vcpkg）
cmake -B build_x64 -G "Visual Studio 17 2022" -A x64 -DVCPKG_MANIFEST_MODE=OFF -DCMAKE_TOOLCHAIN_FILE=""
# 构建
cmake --build build_x64 --config Release -- /m
# 输出：build_x64\bin\Release\x64dbg_mcp.dp64
```
对于 x86：
```powershell
cmake -B build_x86 -G "Visual Studio 17 2022" -A Win32 -DVCPKG_MANIFEST_MODE=OFF -DCMAKE_TOOLCHAIN_FILE="" -DXDBG_ARCH=x86
cmake --build build_x86 --config Release -- /m
# 输出：build_x86\bin\Release\x32dbg_mcp.dp32
```
**输出文件**（在 `dist/` 目录中，或构建脚本后在 `build_x64/bin/Release/` 中）：
- x64 插件：`x64dbg_mcp.dp64`
- x86 插件：`x32dbg_mcp.dp32`
## 安装
1. 将编译的插件复制到其各自的调试器目录：
```powershell
# 对于 x64dbg（64 位）
# 将 <x64dbg-path> 替换为您的实际 x64dbg 安装目录
copy dist\x64dbg_mcp.dp64 <x64dbg-path>\x64\plugins\
# 对于 x32dbg（32 位）
copy dist\x32dbg_mcp.dp32 <x64dbg-path>\x32\plugins\
# 示例（如果安装在 C:\x64dbg）：
# copy dist\x64dbg_mcp.dp64 C:\x64dbg\x64\plugins\
# copy dist\x32dbg_mcp.dp32 C:\x64dbg\x32\plugins\
```
2. （可选）复制配置文件：
```powershell
# 对于 x64dbg
mkdir <x64dbg-path>\x64\plugins\x64dbg-mcp
copy config.json <x64dbg-path>\x64\plugins\x64dbg-mcp\
# 对于 x32dbg
mkdir <x64dbg-path>\x32\plugins\x32dbg-mcp
copy config.json <x64dbg-path>\x32\plugins\x32dbg-mcp\
```
3. 重启 x64dbg/x32dbg 以加载插件
## 用法
### 启动服务器
1. 打开 x64dbg
2. 导航到 **插件 → MCP 服务器 → 启动 MCP HTTP 服务器**
3. 服务器将在配置的端口（默认为 3000）上启动
4. 在 `http://127.0.0.1:3000` 访问服务器
### 配置
编辑 `config.json` 以自定义设置：
```json
{
"version": "1.0.7",
"server": {
"address": "0.0.0.0",
"port": 3000
},
"permissions": {
"allow_memory_write": true,
"allow_register_write": true,
"allow_script_execution": true,
"allow_breakpoint_modification": true,
"allowed_methods": ["debug.*", "register.*", "memory.*", "breakpoint.*", "..."]
},
"logging": {
"enabled": true,
"level": "info",
"file": "x64dbg_mcp.log",
"max_file_size_mb": 10
},
"timeout": {
"request_timeout_ms": 30000,
"step_timeout_ms": 10000,
"memory_read_timeout_ms": 5000
},
"features": {
"enable_notifications": true,
"enable_heartbeat": true,
"heartbeat_interval_seconds": 30,
"enable_batch_requests": true
}
}
```
> **注意**：此分支默认所有接口为 `0.0.0.0`，并启用所有权限，以便于远程调试。根据需要限制生产环境。
### 客户端示例
使用 HTTP 的 Python 客户端示例：
```python
import requests
import json
class MCPClient:
def __init__(self, host='127.0.0.1', port=3000):
self.base_url = f"http://{host}:{port}"
self.request_id = 1
def call(self, method, params=None):
request = {
"jsonrpc": "2.0",
"id": self.request_id,
"method": method,
"params": params or {}
}
self.request_id += 1
response = requests.post(
f"{self.base_url}/rpc",
json=request,
headers={"Content-Type": "application/json"}
)
return response.json()
def subscribe_events(self):
"""订阅 SSE 事件"""
response = requests.get(
f"{self.base_url}/sse",
stream=True,
headers={"Accept": "text/event-stream"}
)
for line in response.iter_lines():
if line:
yield line.decode('utf-8')
# 用法
client = MCPClient()
print(client.call("initialize"))
print(client.call("tools/list"))
print(client.call("resources/list"))
print(client.call("prompts/list"))
# 订阅调试事件
for event in client.subscribe_events():
print(f"事件：{event}")
```
光标和其他 MCP 客户端通常根据 `initialize` 响应的功能决定显示哪些部分。该服务器宣传 `tools`、`resources` 和 `prompts`，因此重新连接后，您应该在客户端 UI 中看到这三个类别。
### VS Code 集成
在 VS Code 设置或 MCP 客户端配置中配置。推荐（流式 HTTP，MCP 2025-03-26）：
```json
{
"mcpServers": {
"x64dbg": {
"type": "http",
"url": "http://127.0.0.1:3000/mcp"
}
}
}
```
旧版 HTTP + SSE 客户端（使用 `/sse` 路径，而不是根路径）：
```json
{
"mcpServers": {
"x64dbg": {
"type": "sse",
"url": "http://127.0.0.1:3000/sse"
}
}
}
```
## 可用方法
### 系统方法
- `system.info` - 获取服务器信息
- `system.ping` - 测试连接
- `system.methods` - 列出所有可用方法
### 调试控制
- `debug.run` - 继续执行
- `debug.pause` - 暂停执行
- `debug.step_into` - 步入指令
- `debug.step_over` - 步过指令
- `debug.step_out` - 步出函数
- `debug.get_state` - 获取当前调试状态
- `debug.run_to` - 运行到特定地址
- `debug.restart` - 重启调试会话
- `debug.stop` - 停止调试
### 寄存器操作
- `register.get` - 读取单个寄存器
- `register.set` - 写入寄存器值
- `register.list` - 列出所有寄存器
- `register.get_batch` - 读取多个寄存器
### 内存操作
- `memory.read` - 读取内存区域
- `memory.write` - 写入内存区域
- `memory.search` - 搜索内存模式
- `memory.get_info` - 获取内存区域信息
- `memory.enumerate` - 列出所有内存区域
- `memory.allocate` - 分配内存
- `memory.free` - 释放已分配的内存
### 断点管理
- `breakpoint.set` - 设置断点
- `breakpoint.delete` - 删除断点
- `breakpoint.enable` - 启用断点
- `breakpoint.disable` - 禁用断点
- `breakpoint.toggle` - 切换断点状态
- `breakpoint.list` - 列出所有断点
- `breakpoint.get` - 获取断点详细信息
- `breakpoint.delete_all` - 删除所有断点
- `breakpoint.set_condition` - 设置断点条件
- `breakpoint.set_log` - 设置断点日志消息
- `breakpoint.reset_hitcount` - 重置断点命中计数
### 反汇编
- `disassembly.at` - 在地址处反汇编
- `disassembly.range` - 反汇编地址范围
- `disassembly.function` - 反汇编整个函数
### 符号解析
- `symbol.resolve` - 将符号解析为地址
- `symbol.from_address` - 从地址获取符号
- `symbol.search` - 按模式搜索符号
- `symbol.list` - 列出所有符号
- `symbol.modules` - 列出加载的模块
- `symbol.set_label` - 设置符号标签
- `symbol.set_comment` - 设置符号注释
- `symbol.get_comment` - 获取符号注释
### 模块操作
- `module.list` - 列出所有加载的模块
- `module.get` - 获取模块信息
- `module.get_main` - 获取主模块
### 线程操作
- `thread.list` - 列出所有线程
- `thread.get_current` - 获取当前线程
- `thread.get` - 获取线程信息
- `thread.switch` - 切换到线程
- `thread.suspend` - 挂起线程
- `thread.resume` - 恢复线程
- `thread.get_count` - 获取线程计数
### 栈操作
- `stack.get_trace` - 获取栈跟踪
- `stack.read_frame` - 读取栈帧
- `stack.get_pointers` - 获取栈指针（RSP, RBP）
- `stack.is_on_stack` - 检查地址是否在栈上
有关完整的 方法签名和示例，请参阅源代码中的内联文档或使用 `system.methods` API 调用。
## 架构
插件分为四层：
1. **通信层**：带有 SSE 支持的 HTTP 服务器，用于实时事件
2. **协议层**：JSON-RPC 和 MCP 协议解析、验证、调度
3. **业务层**：调试操作、内存管理、符号解析
4. **插件层**：x64dbg 集成、事件处理、回调管理
### 关键组件
- **MCPHttpServer**：带有 SSE 端点用于事件流的 HTTP 服务器
- **MethodDispatcher**：路由 JSON-RPC 调用到适当的处理程序
- **业务管理器**：DebugController、MemoryManager、RegisterManager 等
- **事件系统**：通过 SSE 的实时调试事件通知
## 安全考虑
> **警告**：此分支配置用于受信任的 LAN 环境。它 **不适合公开部署。
- 所有写入权限在此分支中 **启用** 以便使用方便
- 服务器默认监听 `0.0.0.0`（所有接口）
- 源/主机验证 **禁用** 以便远程访问
- 速率限制 **禁用**
- CORS 配置为允许所有源
- 请根据需要限制 `config.json` 权限并将地址更改为 `127.0.0.1`
## 故障排除
### 插件未加载
- 确保插件文件位于正确的目录中
- 检查 x64dbg 日志中的错误消息
- 验证 x64dbg 版本兼容性（需要 2023+ 版本的 x64dbg）
### 服务器无法启动
- 检查端口 3000 是否已被占用
- 验证 `config.json` 是否为有效的 JSON
- 检查插件目录的文件权限
- 查看 x64dbg 日志文件以获取详细的错误消息
### 连接被拒绝
- 确保 HTTP 服务器已通过插件菜单启动（“启动 MCP HTTP 服务器”）
- 检查端口 3000 的防火墙设置
- 验证客户端是否连接到 `http://<主机 IP 地址>:3000`
- 尝试在 Web 浏览器中访问 URL 以进行测试
- 对于远程连接，请确保机器的防火墙允许传入 TCP 3000
## 贡献
欢迎贡献！请：
1. 分叉仓库
2. 创建一个功能分支
3. 使用清晰的提交消息进行更改
4. 提交拉取请求
## 许可
该项目根据 MIT 许可协议许可 - 有关详细信息，请参阅 LICENSE 文件。
## 致谢
- [x64dbg](https://x64dbg.com/) - 本插件扩展的调试器
- [nlohmann/json](https://github.com/nlohmann/json) - JSON 库
- [SetsunaYukiOvO/x64dbg-mcp](https://github.com/SetsunaYukiOvO/x64dbg-mcp) - 原始项目
- 模型上下文协议规范
## 联系方式
- GitHub 问题：用于错误报告和功能请求
---
**注意**：这是实验性软件。请自担风险。在使用关键应用程序之前，请始终在安全环境中进行测试。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器