x64调试器-mcp

作者：SetsunaYukiOvO2 星标更新：2025-11-20

安装使用来源：spider==github.com

项目介绍

x64dbg MCP 服务器插件

英文 | 中文

这是一个为 x64dbg 实现的 Model Context Protocol (MCP) 服务器，通过 JSON-RPC 2.0 接口支持远程调试。此插件允许外部应用程序和 AI 代理以编程方式与 x64dbg 调试器进行交互。

功能

JSON-RPC 2.0 协议：标准的、语言无关的接口
HTTP + SSE 通信：通过 Server-Sent Events 实现现代基于 Web 的集成
MCP 协议支持：兼容用于 AI 代理集成的 Model Context Protocol
全面的调试 API：
- 执行控制（运行、暂停、单步）
- 内存读取/写入/搜索
- 寄存器访问（超过 50 个寄存器）
- 断点管理（软件断点、硬件断点、内存断点）
- 汇编和符号解析
- 通过 SSE 发送事件通知
安全性：基于权限的访问控制
可扩展性：插件架构支持自定义方法

从源码构建

预备条件

Windows 10/11 (x64)
CMake 3.15 或更高版本
Visual Studio 2022 带有 C++ 桌面开发工作负载
vcpkg - C++ 库的包管理器
Git - 用于克隆仓库

快速构建

最简单的构建方式是使用提供的构建脚本：

# 克隆仓库
git clone https://github.com/SetsunaYukiOvO/x64dbg-mcp.git
cd x64dbg-mcp

# 运行构建脚本
.\build.bat

# 脚本会：
# 1. 自动检测或安装 vcpkg
# 2. 下载依赖项（nlohmann_json）
# 3. 使用正确的设置配置 CMake
# 4. 使用 Visual Studio 构建
# 5. 可选地安装到 x64dbg 插件目录

构建脚本选项：

.\build.bat           # 发布版构建（默认）
.\build.bat --debug   # 调试版构建带符号
.\build.bat --clean   # 清理后重新构建
.\build.bat --help    # 显示所有选项

手动构建步骤

如果你更喜欢手动控制：

安装 vcpkg（如果尚未安装）：

git clone https://github.com/Microsoft/vcpkg.git C:\vcpkg
C:\vcpkg\bootstrap-vcpkg.bat
setx VCPKG_ROOT "C:\vcpkg"

克隆仓库：

git clone https://github.com/SetsunaYukiOvO/x64dbg-mcp.git
cd x64dbg-mcp

使用 CMake 配置：

cmake -B build -G "Visual Studio 17 2022" -A x64 ^
    -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake

构建：

cmake --build build --config Release

输出：

插件文件：build\bin\Release\x64dbg_mcp.dp64（大约 445 KB）

安装

将编译好的插件复制到 x64dbg 的插件目录：

cp build/bin/Release/x64dbg_mcp.dp64 /path/to/x64dbg/plugins/

复制配置文件：

mkdir -p /path/to/x64dbg/plugins/x64dbg-mcp
cp config.json /path/to/x64dbg/plugins/x64dbg-mcp/

重启 x64dbg 以加载插件

使用

启动服务器

打开 x64dbg
导航至 插件 → MCP 服务器 → 启动 MCP HTTP 服务器
服务器将在配置的端口上启动（默认：3000）
访问服务器 http://127.0.0.1:3000

配置

编辑 config.json 以定制设置：

{
  "version": "1.0.1",
  "server": {
    "address": "127.0.0.1",
    "port": 3000
  },
  "permissions": {
    "allow_memory_write": true,
    "allow_register_write": true,
    "allow_script_execution": true,
    "allow_breakpoint_modification": true
  },
  "logging": {
    "enabled": true,
    "level": "info",
    "file": "x64dbg_mcp.log"
  }
}

客户端示例

使用 HTTP 的 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"))

# 订阅调试事件
for event in client.subscribe_events():
    print(f"事件: {event}")

VS Code 集成

在 VS Code 设置或 MCP 客户端配置中配置：

{
  "mcpServers": {
    "x64dbg": {
      "url": "http://127.0.0.1:3000",
      "transport": "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 调用。

架构

插件分为四层：

通信层：带有 SSE 支持的 HTTP 服务器，用于实时事件
协议层：JSON-RPC 和 MCP 协议解析、验证、分派
业务层：调试操作、内存管理、符号解析
插件层：x64dbg 集成、事件处理、回调管理

关键组件

MCPHttpServer：带有 SSE 端点的 HTTP 服务器，用于事件流
MethodDispatcher：将 JSON-RPC 调用路由到适当的处理器
业务管理器：DebugController, MemoryManager, RegisterManager 等
事件系统：通过 SSE 实时发送调试事件通知

安全注意事项

默认情况下，内存和寄存器写入操作是禁用的
只在需要时在 config.json 中启用写入权限
服务器默认监听本地主机（127.0.0.1）
单客户端连接限制防止资源耗尽
所有操作都需要调试器处于暂停状态

故障排除

插件未加载

确保插件文件位于正确目录
查看 x64dbg 日志以获取错误信息
验证 x64dbg 版本兼容性（需要 x64dbg 构建 2023+）

服务器无法启动

检查端口 3000 是否已被占用
验证 config.json 是有效的 JSON
检查插件目录的文件权限
查看 x64dbg 日志文件以获取详细错误信息

连接被拒绝

确保通过插件菜单启动 HTTP 服务器（“启动 MCP HTTP 服务器”）
检查防火墙设置以允许端口 3000
验证客户端是否连接到 http://127.0.0.1:3000
尝试在浏览器中访问 http://127..0.1:3000 来测试

贡献

欢迎贡献！请：

分叉仓库
创建一个特性分支
使用清晰的提交信息进行更改
提交拉取请求

许可证

该项目采用 MIT 许可证 - 详见 LICENSE 文件。

致谢

x64dbg - 此插件扩展的调试器
nlohmann/json - JSON 库
Model Context Protocol 规范

联系

GitHub Issues：用于报告错误和提出功能请求

注意：这是实验性软件。请自行承担风险。在关键应用中使用前，请始终在一个安全环境中进行测试。