内容
# x64dbg MCP
  
x64dbg 的模型上下文协议（MCP）服务器。它向兼容 MCP 的 AI 客户端（如 Claude Desktop、Cursor 等）公开 x64dbg 的调试和逆向工程能力，使 LLM 可以驱动实时调试会话：读取内存和寄存器、设置断点、步进执行、反汇编、搜索、修补、转储模块等。整个项目共有 36 个工具，暴露了 393 个独立操作，以及 15 个资源和 10 个提示。
该项目仅支持 Windows（64 位和 32 位）。它有两个组件，分别作为独立进程运行，通过环回接口上的 HTTP 进行通信。
## 亮点
- **分组工具设计。** 每个工具都有一个 `action` 参数，用于选择特定的操作，因此一个工具涵盖了一整套相关的端点，而不需要为每个命令单独创建一个工具。这使得工具列表保持紧凑，同时暴露了 393 多个独立操作。
- **原生 x64dbg 集成。** 作为一个真正的插件，带有菜单、设置对话框和自动启动加载。它在 x64dbg 内运行，直接调用 SDK - 没有脚本桥或外部自动化层。
- **C++ 插件加上 TypeScript 服务器。** 插件使用 C++23，直接访问 SDK，低开销；服务器使用 TypeScript，基于官方 `@modelcontextprotocol/sdk`，与客户端使用 stdio 通信。
- **弹性连接。** 自动健康监测、重新连接和重试逻辑意味着工具调用可以在插件短暂离线时生存（例如，x64dbg 重启目标时）。
- **默认仅限本地主机。** 绑定到 `127.0.0.1`，支持可选的 bearer token。API 永远不会暴露给网络或本地浏览器。
## 快速开始
目前这是一个从源代码构建的项目；不提供预先构建的下载。端到端流程分为四个步骤，每个步骤在下面的章节中有详细介绍：
1. **构建插件** - 安装先决条件，然后在 `plugin/` 中运行 `fetch-sdk.ps1` 和 CMake 以生成 `x64dbg_mcp.dp64`（或 `.dp32`）。
2. **构建服务器** - 在 `server/` 中运行 `npm install && npm run build`。
3. **安装插件** - 将 `.dp64`/`.dp32` 文件放入匹配的 x64dbg `plugins` 文件夹中并启动 x64dbg。
4. **指向 MCP 客户端的服务器** - 将服务器添加到客户端配置中并重启客户端。
如果有人已经为您构建了插件，您只需要步骤 3 和 4。
## 工作原理
```mermaid
flowchart LR
A[MCP Client] <-->|stdio JSON-RPC| B[TypeScript MCP Server]
B <-->|HTTP REST on 127.0.0.1:27042| C[C++ Plugin inside x64dbg]
C -->|x64dbg SDK| D[Debugged Process]
```
- **`server/`** - TypeScript MCP 服务器（`@modelcontextprotocol/sdk`），与 MCP 客户端使用 stdio 通信。它注册了 36 个工具、15 个资源和 10 个提示。每个工具调用被转换为一个或多个针对插件的 HTTP 请求。
- **`plugin/`** - C++23 x64dbg 插件（`x64dbg_mcp.dp64` / `.dp32`），在 x64dbg 内运行。它启动一个小型 HTTP 服务器，分派请求到调用 x64dbg SDK 的处理程序，并返回 JSON 结果。它仅绑定到 `127.0.0.1`，绝不将 API 暴露给网络。
MCP 客户端启动服务器；服务器连接到已经加载到 x64dbg 中的插件。两者不需要按特定顺序启动 - 服务器等待插件上线。
## 先决条件
### 服务器
- [Node.js](https://nodejs.org/) 18 或更高版本（包括 npm）。
### 插件（从源代码构建）
- Windows 10 或更高版本。
- [x64dbg](https://x64dbg.com) （快照构建）。这是加载插件的内容。
- [Visual Studio 2022](https://visualstudio.microsoft.com/)，带有 **C++ 开发** 工作负载，以及可选组件 **C++ Clang 工具 for Windows** （提供 `clang-cl`）。
- [CMake](https://cmake.org/) 3.25 或更高版本（需要 CMakePresets 版本 6）。
- [Ninja](https://ninja-build.org/) （与 VS C++ 工作负载捆绑；否则单独安装并放入 `PATH`）。
- [vcpkg](https://github.com/microsoft/vcpkg)，带有 `VCPKG_ROOT` 环境变量指向您的 vcpkg 检出。
- 互联网访问权限，用于第一次插件构建（x64dbg 插件 SDK 从 GitHub 下载；后续构建被缓存，可以离线工作）。
> 如果您只需要使用该项目，并且有人已经为您构建了插件，您可以跳过插件构建工具链，只需将编译的 `.dp64` 文件复制到 x64dbg 中。
## 构建
### 1. 设置 vcpkg（一次）
克隆并引导 vcpkg，然后设置 `VCPKG_ROOT` 以便 CMake 可以找到它：
```powershell
git clone https://github.com/microsoft/vcpkg.git C:\vcpkg
C:\vcpkg\bootstrap-vcpkg.bat
setx VCPKG_ROOT "C:\vcpkg"
```
在 `setx` 后打开一个新的终端，使变量生效。
### 2. 构建插件
插件需要 x64dbg 插件 SDK（头文件和导入库）。`fetch-sdk.ps1` 脚本从最新的 x64dbg GitHub 版本下载它，并缓存在 `plugin/sdk/` 下。
```powershell
cd plugin
.\fetch-sdk.ps1
cmake --preset x64-release
cmake --build --preset x64-release
```
这会生成 `plugin/build/x64-release/bin/x64dbg_mcp.dp64`。
要构建 32 位插件，请使用 `x32-release` 预设，生成 `x64dbg_mcp.dp32`，位于 `plugin/build/x32-release/bin/` 下。可以使用 `x64-debug` 预设进行调试构建。
### 3. 构建服务器
```powershell
cd server
npm install
npm run build
```
这会将 TypeScript 编译到 `server/dist/`。入口点是 `server/dist/index.js`。
## 在 x64dbg 中安装插件
1. 找到您的 x64dbg 安装。它包含一个 `x64` 文件夹（用于 64 位调试器）和一个 `x32` 文件夹（用于 32 位调试器）。
2. 将匹配的文件复制到调试器可执行文件旁边的 `plugins` 文件夹中：
- 64 位：将 `x64dbg_mcp.dp64` 复制到 `<x64dbg>\x64\plugins\`
- 32 位：将 `x64dbg_mcp.dp32` 复制到 `<x64dbg>\x32\plugins\`
3. 启动 x64dbg。一个新的 **x64dbg MCP** 菜单出现，带有 **启动服务器**、**停止服务器**、**设置...** 和 **关于...** 条目。服务器默认自动启动。
您可以在 x64dbg 日志窗口中确认服务器正在运行，或在 x64dbg 命令行中运行 `mcpserver status` 命令。`mcpserver` 命令还接受 `start` 和 `stop`。
## 配置 MCP 客户端
将服务器添加到 MCP 客户端的配置中。服务器使用 stdio，因此客户端将其作为子进程启动，并通过标准流进行通信。
示例配置（Claude Desktop `claude_desktop_config.json`，位于 Windows 上 `%APPDATA%\Claude\claude_desktop_config.json`）：
```json
{
"mcpServers": {
"x64dbg": {
"command": "node",
"args": ["C:/path/to/x64dbg-MCP/server/dist/index.js"],
"env": {
"X64DBG_MCP_HOST": "127.0.0.1",
"X64DBG_MCP_PORT": "27042"
}
}
}
}
```
将 `args` 路径调整为您的 `server/dist/index.js` 在机器上的绝对位置。保存文件后重启客户端。
### 环境变量
所有变量均为可选。默认值与插件默认值匹配，因此股票设置不需要任何变量。
| 变量 | 默认值 | 描述 |
|---|---|---|
| `X64DBG_MCP_HOST` | `127.0.0.1` | 插件 HTTP 服务器监听的主机。 |
| `X64DBG_MCP_PORT` | `27042` | 插件 HTTP 服务器监听的端口。 |
| `X64DBG_MCP_TIMEOUT` | `0` | 每个请求的超时时间（毫秒）。`0` 等待无限时间（适用于 tracing 等长时间操作）。 |
| `X64DBG_MCP_RETRIES` | `3` | 请求失败时的重试次数。 |
| `X64DBG_MCP_TOKEN` | （空） | 发送到插件进行身份验证的 bearer token。留空除非您在插件设置中设置了匹配的 token。 |
可以在 x64dbg 中通过插件的 **设置...** 对话框更改相同的主机、端口和 token，并跨会话保存。
## 运行
1. 启动 x64dbg 并打开或附加到目标进程。插件的 HTTP 服务器在加载时自动启动。
2. 启动（或重启）您的 MCP 客户端。它启动服务器，服务器轮询插件直到可达。
3. 从客户端调用任意公开的工具。大多数操作需要活动调试会话（加载目标）；在没有调试会话的情况下进行的调用返回冲突错误。
## 连接行为
- 启动时，服务器每 15 秒开始轮询 `GET /api/health`。
- 在第一次工具调用时，如果插件尚未可达，服务器最多等待 120 秒（每 2 秒轮询一次），然后如果插件仍不可达，则失败并显示明确的错误。
- 如果插件在会话中途断线（例如，x64dbg 关闭），服务器标记自己为断开连接，并在下一次调用时重试。
- 连接错误导致失败的请求最多重试 `X64DBG_MCP_RETRIES` 次，延迟时间增加；插件返回的 HTTP 错误（4xx/5xx）立即返回，不会重试。
## 公开内容
### 工具（36 个）
每个工具都有一个 `action` 参数，用于选择特定的操作，因此一个工具涵盖了一组相关的端点。这种分组设计使得 36 个工具公开了 393 多个操作，同时保持工具列表紧凑和自描述。最常用于驱动会话的工具以 **粗体** 显示。
| 工具 | 用途 |
|---|---|
| **`x64dbg_debug`** | 运行、暂停、步进（进入/越过/退出）、初始化、附加、分离、重启、运行到、以及状态查询 |
| `x64dbg_command` | 执行 x64dbg 命令、求值表达式、运行脚本、读写数据库 |
| `x64dbg_registers` | 读取所有/单个寄存器、写入寄存器、读取标志和 AVX-512 状态 |
| **`x64dbg_memory`** | 读取、写入、分配、释放、保护和查询页面和有效性 |
| `x64dbg_disassembly` | 在地址处反汇编或整个函数；组装指令 |
| **`x64dbg_breakpoints`** | 设置/删除/列出/切换软件、硬件和内存断点，并配置条件 |
| `x64dbg_symbols` | 将名称解析为地址，反之亦然；列出和搜索模块符号 |
| `x64dbg_stack` | 读取堆栈、遍历调用堆栈、读取返回地址和 SEH 链 |
| `x64dbg_threads` | 列出、切换、挂起、恢复、创建和杀死线程 |
| `x64dbg_modules` | 列出模块并读取基地址、节、党派、导入和导出 |
| **`x64dbg_search`** | 在内存中搜索字节模式、字符串、引用和组装指令 |
| `x64dbg_find_pattern` | 搜索汇编指令模式（间接调用、堆栈访问、API 调用、跳转表） |
| `x64dbg_analysis` | 函数边界、交叉引用、基本块、常量、错误代码、源位置 |
| `x64dbg_database` | 列出常量、错误代码、结构体和模块字符串 |
| `x64dbg_address_convert` | 在虚拟地址和文件偏移之间转换 |
| `x64dbg_watchdog` | 检查监视表达式 watchdog 状态 |
| `x64dbg_analyze_module` | 在单个调用中运行多个分析传递 |
| `x64dbg_events` | 订阅和取消订阅调试器事件（断点命中、异常、模块加载） |
| **`x64dbg_tracing`** | 跟踪进入/越过并记录，配置跟踪文件和记录 |
| `x64dbg_dumping` | 转储内存和模块，解析 PE 头、节、导入、导出和重定位 |
| `x64dbg_antidebug` | 读取 PEB/TEB、隐藏调试器并检查 DEP 状态 |
| `x64dbg_exceptions` | 配置异常断点和列出异常代码 |
| `x64dbg_process` | 进程详细信息、命令行、提升和调试器版本 |
| `x64dbg_handles` | 枚举句柄、TCP 连接、窗口和堆 |
| `x64dbg_control_flow` | 控制流图、分支目标、循环和函数定义 |
| `x64dbg_patches` | 应用、列出、恢复和导出补丁 |
| `x64dbg_advanced_dump` | 模块分析、OEP 检测、PE 重建和可配置的转储 |
| `x64dbg_context` | 捕获和比较调试器状态快照 |
| `x64dbg_function` | 列出函数并读取函数边界 |
| **`x64dbg_script`** | 执行脚本、批处理命令、多步脚本引擎运行和带有分支的条件工作流 |
| `x64dbg_system` | 服务器信息、ping、方法列表和权限 |
| `x64dbg_assembler` | 在地址处组装指令 |
| `x64dbg_bookmark` | 设置、删除和列出书签 |
| `x64dbg_snapshot_diff` | 捕获和比较命名状态快照 |
| **`x64dbg_auto_patch`** | 应用常见补丁模式（NOP、JMP、条件逆转、RET、设置字节） |
| `x64dbg_batch_annotate` | 在单个调用中设置多个标签、注释或书签 |
### 资源（15 个）
客户端可以按 URI 需求获取状态：
- `x64dbg://state`、`x64dbg://registers`、`x64dbg://modules`、`x64dbg://threads`、
`x64dbg://memory_map`、`x64dbg://breakpoints`、`x64dbg://stack`、
`x64dbg://stack_trace`
- 参数化模板：`x64dbg://memory/{address}/{size}`、`x64dbg://disassembly/{address}/{count}`、
`x64dbg://module/{name}`、`x64dbg://symbol/{name}`、`x64dbg://function/{address}`、
`x64dbg://export/{module}`、`x64dbg://import/{module}`
### 提示（10 个）
客户端可以调用预构建的工作流：`debug_session`、`analyze_crash`、
`unpack_binary`、`trace_function`、`find_vulnerability`、`reverse_algorithm`、
`api_monitor`、`patch_code`、`hunt_strings`、`compare_state`。
## 性能和可靠性
- **原生插件，不是自动化。** 插件是编译的 C++ 代码，在 x64dbg 中运行，直接调用 SDK。工具调用不经过脚本层，因此每个调用的开销很低。
- **自动重新连接。** 如果在调用工具时插件不可达（例如，x64dbg 正在重启目标），服务器等待它重新上线，然后重试。参见 [连接行为](#connection-behavior)。
- **重试并退避。** 连接级失败最多重试 `X64DBG_MCP_RETRIES` 次，并增加延迟；插件返回的 HTTP 错误立即返回，因此您获得快速、清晰的反馈。
- **状态快照和监视狗。** `x64dbg_context`、`x64dbg_snapshot_diff` 和 `x64dbg_watchdog` 工具让客户端捕获状态、比较它在步骤之间，并通知当监视的表达式发生变化 - 在您不想手动轮询的情况下非常有用。
- **支持长时间操作。** `X64DBG_MCP_TIMEOUT` 默认值为 `0`（无限等待），因此诸如跟踪或运行到断点之类的操作不会因客户端超时而被缩短。
## 项目布局
```
.
├── server/ TypeScript MCP 服务器
│ ├── src/
│ │ ├── index.ts 入口点；创建 stdio 上的 MCP 服务器
│ │ ├── config.ts 读取环境变量
│ │ ├── http_client.ts HTTP 客户端、健康监测、重试
│ │ ├── tools/ 工具注册，按类别分组
│ │ ├── resources/ 资源注册
│ │ └── prompts/ 提示语注册
│ ├── package.json
│ ├── tsconfig.json
│ └── server.json 工具/资源/提示清单
└── plugin/ C++ x64dbg 插件
├── src/
│ ├── plugin_main.cpp 插件生命周期、菜单、设置、路由连接
│ ├── http/ HTTP 服务器、路由器、请求/响应结构体
│ ├── bridge/ 调用 x64dbg SDK 的适配器
│ ├── handlers/ HTTP 路由处理程序，按类别分组
│ ├── ui/ 设置和关于对话框
│ ├── util/ 格式化帮助程序和共享跟踪状态
│ └── resources/ 嵌入式插件图标
├── CMakeLists.txt
├── CMakePresets.json
├── vcpkg.json
├── fetch-sdk.ps1 下载 x64dbg 插件 SDK
└── plugin.def 导出插件入口点
```
## 安全说明
- 插件仅绑定到 `127.0.0.1`。它无法从其他计算机访问。
- HTTP 响应故意省略 CORS 头，因此本地浏览器中的网页无法驱动调试器。API 仅供本地 Node 服务器使用。
- 支持身份验证。如果您在插件设置中设置了身份验证令牌，服务器必须发送相同的令牌（`X64DBG_MCP_TOKEN`），否则请求将被拒绝为 401。如果未设置令牌，则不需要身份验证。
## 故障排除
- **插件未出现在 x64dbg 中。** 确认文件位于正确的 `plugins` 文件夹中，并且架构匹配（`dp64` 与 64 位调试器、`dp32` 与 32 位调试器）。检查 x64dbg 日志中的加载错误。
- **服务器报告插件不可达。** 确保 x64dbg 运行并加载插件，并且没有其他人使用端口 27042。如果您在插件设置中更改了端口，请将 `X64DBG_MCP_PORT` 设置为匹配。
- **CMake 配置失败。** 验证 `VCPKG_ROOT` 是否在当前终端中设置，以及 `clang-cl` 和 `ninja` 是否在 `PATH` 上（分别通过 VS C++ 和 Clang 组件安装）。
- **`fetch-sdk.ps1` 失败。** 它在第一次运行需要互联网访问来下载 SDK。如果它在 SDK 已经缓存后失败，构建可以继续使用现有的本地副本。
## 许可证
MIT
