# X64Dbg MCP Server

<div align="center">
  <img src="logo.png" alt="X64Dbg MCP Logo" width="200">
</div>

X64Dbg的Model Context Protocol服务器，用于AI辅助逆向分析和调试。

## 功能特性

<details>
<summary>点击展开查看完整功能列表（共40+项）</summary>

- ✅ 执行x64dbg调试命令
- ✅ 获取寄存器信息
- ✅ 获取模块列表
- ✅ 设置/删除/启用/禁用断点
- ✅ 条件断点支持
- ✅ 读取/写入内存
- ✅ 内存保护属性管理
- ✅ 反汇编代码
- ✅ 单步调试（Step Over/Into）
- ✅ 继续/暂停执行
- ✅ 获取堆栈信息
- ✅ 搜索内存模式
- ✅ 脚本执行结果解析
- ✅ 日志输出捕获
- ✅ 内存转储功能
- ✅ 符号解析
- ✅ 硬件断点支持
- ✅ 数据断点（监视点）
- ✅ 进程附加/分离
- ✅ 代码补丁管理
- ✅ 代码注入（Shellcode注入）
- ✅ DLL注入/卸载
- ✅ 反调试绕过
- ✅ 异常处理设置
- ✅ 文件操作（加载/保存）
- ✅ 内存比较和填充
- ✅ 地址计算和格式化工具
- ✅ 寄存器值修改（单个/批量）
- ✅ 断点命中计数
- ✅ 书签管理
- ✅ 线程操作（切换/挂起/恢复/上下文）
- ✅ 执行跟踪
- ✅ 内存分配/释放
- ✅ 表达式计算
- ✅ 批量操作（断点/内存）
- ✅ 结构体查看
- ✅ 脚本管理
- ✅ 配置管理
- ✅ 性能分析

</details>

## 安装

### 1. 安装Python依赖

```bash
pip install -r requirements.txt
```

或使用uv（推荐）：

```bash
uv pip install -r requirements.txt
```

### 2. 配置x64dbg路径

#### 方法一：自动检测（推荐）

系统会自动检测以下常见路径：
- `D:\baiyajin-code\x64dbg\release\x64\x64dbg.exe` (开发环境)
- `C:\Program Files\x64dbg\release\x64\x64dbg.exe` (标准安装)
- `C:\Program Files (x86)\x64dbg\release\x64\x64dbg.exe` (32位系统)
- `%USERPROFILE%\x64dbg\release\x64\x64dbg.exe` (用户目录)
- `C:\x64dbg\release\x64\x64dbg.exe` (其他常见位置)
- `D:\x64dbg\release\x64\x64dbg.exe` (其他常见位置)
- 以及其他常见位置

如果x64dbg安装在上述位置之一，**无需额外配置**，系统会自动检测并使用。

#### 方法二：手动配置

如果x64dbg安装在其他位置，编辑 `config.py`，修改以下行：

```python
DEFAULT_X64DBG_PATH = r"你的x64dbg路径\x64dbg.exe"
DEFAULT_X64DBG_PLUGIN_DIR = r"你的x64dbg路径\plugins"
```

例如：
```python
DEFAULT_X64DBG_PATH = r"D:\MyTools\x64dbg\release\x64\x64dbg.exe"
DEFAULT_X64DBG_PLUGIN_DIR = r"D:\MyTools\x64dbg\release\x64\plugins"
```

#### 方法三：环境变量

设置环境变量 `X64DBG_PATH` 指向x64dbg.exe的完整路径：

**Windows PowerShell:**
```powershell
$env:X64DBG_PATH = "D:\baiyajin-code\x64dbg\release\x64\x64dbg.exe"
```

**Windows CMD:**
```cmd
set X64DBG_PATH=D:\baiyajin-code\x64dbg\release\x64\x64dbg.exe
```

**永久设置（系统环境变量）:**
1. 右键"此电脑" -> "属性" -> "高级系统设置" -> "环境变量"
2. 在"用户变量"或"系统变量"中添加：
   - 变量名：`X64DBG_PATH`
   - 变量值：`D:\baiyajin-code\x64dbg\release\x64\x64dbg.exe`

#### 验证配置

启动MCP服务器后，如果x64dbg未安装或路径错误，工具调用时会返回清晰的错误提示，指导用户如何配置。MCP服务器本身可以正常启动，只有在调用工具时才会提示需要配置x64dbg路径。

### 3. 安装x64dbg Python插件

确保x64dbg已安装Python插件（Python插件通常是x64dbg自带的）。

## 使用方法

### 在Cursor中配置（推荐）

Cursor支持通过项目配置文件或全局配置文件来设置MCP服务器。

#### 方法一：项目级配置（推荐）

1. **创建配置文件目录**

   在项目根目录下创建 `.cursor` 文件夹（如果不存在）：

   ```bash
   mkdir .cursor
   ```

2. **创建MCP配置文件**

   在 `.cursor` 文件夹中创建 `mcp.json` 文件，添加以下配置：

   ```json
   {
     "mcpServers": {
       "x64dbg-mcp": {
         "command": "python",
         "args": [
           "${workspaceFolder}/main.py"
         ],
         "env": {
           "PYTHONPATH": "${workspaceFolder}"
         }
       }
     }
   }
   ```

   **使用uv（推荐）**：

   ```json
   {
     "mcpServers": {
       "x64dbg-mcp": {
         "command": "uv",
         "args": [
           "run",
           "python",
           "${workspaceFolder}/main.py"
         ],
         "cwd": "${workspaceFolder}"
       }
     }
   }
   ```

3. **重启Cursor**

   保存配置文件后，重启Cursor IDE以使配置生效。

4. **验证配置**

   - 打开Cursor设置（`Ctrl+,` 或 `Cmd+,`）
   - 导航到 `Features` > `MCP` 或 `设置` > `功能` > `MCP`
   - 确认 `x64dbg-mcp` 服务器显示为已启用状态（绿色指示器）

#### 方法二：全局配置

1. **找到Cursor配置目录**

   - **Windows**: `%APPDATA%\Cursor\User\globalStorage\mcp.json` 或 `%USERPROFILE%\.cursor\mcp.json`
   - **macOS**: `~/Library/Application Support/Cursor/User/globalStorage/mcp.json` 或 `~/.cursor/mcp.json`
   - **Linux**: `~/.config/Cursor/User/globalStorage/mcp.json` 或 `~/.cursor/mcp.json`

2. **编辑全局配置文件**

   打开或创建 `mcp.json` 文件，添加以下配置（请将路径替换为你的实际项目路径）：

   ```json
   {
     "mcpServers": {
       "x64dbg-mcp": {
         "command": "python",
         "args": [
           "D:\\baiyajin-code\\x64dbg-mcp\\main.py"
         ],
         "env": {
           "PYTHONPATH": "D:\\baiyajin-code\\x64dbg-mcp"
         }
       }
     }
   }
   ```

   **使用uv（推荐）**：

   ```json
   {
     "mcpServers": {
       "x64dbg-mcp": {
         "command": "uv",
         "args": [
           "run",
           "python",
           "D:\\baiyajin-code\\x64dbg-mcp\\main.py"
         ],
         "cwd": "D:\\baiyajin-code\\x64dbg-mcp"
       }
     }
   }
   ```

3. **重启Cursor**

   保存配置文件后，重启Cursor IDE。

#### 配置说明

- **`command`**: 运行MCP服务器的命令（`python` 或 `uv`）
- **`args`**: 传递给命令的参数数组
  - `${workspaceFolder}`: Cursor会自动替换为当前工作区路径
  - 全局配置中需要使用绝对路径
- **`env`**: 环境变量（可选）
  - `PYTHONPATH`: 确保Python能找到项目模块
- **`cwd`**: 工作目录（使用uv时推荐设置）

#### 使用MCP工具

配置完成后，在Cursor的AI对话中可以直接使用x64dbg工具：

- "获取当前寄存器值"
- "在地址0x401000设置断点"
- "反汇编0x401000地址的代码"
- "读取0x401000地址的内存"

### 在Claude Desktop中配置

1. 打开Claude Desktop配置文件（Windows: `%APPDATA%\Claude\claude_desktop_config.json`）

2. 添加MCP服务器配置：

```json
{
  "mcpServers": {
    "x64dbg-mcp": {
      "command": "python",
      "args": [
        "D:\\baiyajin-code\\wx\\x64dbg-mcp\\main.py"
      ],
      "env": {
        "PYTHONPATH": "D:\\baiyajin-code\\wx\\x64dbg-mcp"
      }
    }
  }
}
```

或使用uv（推荐，会自动处理依赖）：

```json
{
  "mcpServers": {
    "x64dbg-mcp": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "D:\\baiyajin-code\\wx\\x64dbg-mcp\\main.py"
      ],
      "cwd": "D:\\baiyajin-code\\wx\\x64dbg-mcp"
    }
  }
}
```

**注意**：请将路径 `D:\\baiyajin-code\\wx\\x64dbg-mcp` 替换为你的实际项目路径。

### 在Cherry Studio中配置

1. 打开Cherry Studio设置
2. 添加MCP服务器：
   - **名称**: X64Dbg-MCP-Server
   - **命令**: `python main.py` 或 `uv run python main.py`
   - **工作目录**: `D:\baiyajin-code\wx\x64dbg-mcp`
   - **环境变量**: 可选，设置PYTHONPATH

## 工作原理

### 命令执行方式

由于x64dbg主要通过GUI和插件系统工作，本MCP服务采用以下方式：

1. **自动执行（推荐）**：MCP服务尝试通过x64dbg的Python插件API自动执行脚本。如果x64dbg正在运行且支持API调用，命令将自动执行。
2. **脚本文件方式**：如果自动执行失败，MCP服务会创建Python脚本文件到x64dbg的plugins目录
3. **手动加载**：在x64dbg中通过 `File -> Script -> Load` 加载脚本执行命令（仅在自动执行不可用时需要）

### 脚本文件位置

脚本文件保存在：`[x64dbg安装目录]/release/x64/plugins/mcp_temp/`

### 自动执行机制

- 当x64dbg的Python插件环境可用时，脚本会自动执行
- 如果不在x64dbg环境中，脚本会保存到文件，等待手动加载
- 所有命令默认启用自动执行，可通过参数控制

## 项目结构

项目采用模块化设计，遵循单一职责原则，每个文件不超过200行。

```
Tools/
├── core/                      # 核心基础模块
│   ├── base_controller.py    # 基础控制器（命令执行）
│   ├── script_executor.py     # 脚本执行器
│   └── result_parser.py       # 结果解析器
├── modules/                   # 功能模块（按功能分类）
│   ├── register.py            # 寄存器操作
│   ├── breakpoint.py          # 断点管理
│   ├── memory.py              # 内存操作（组合模块）
│   ├── memory_basic.py        # 内存基础操作
│   ├── memory_advanced.py     # 内存高级操作
│   ├── thread.py              # 线程管理
│   ├── process.py             # 进程管理
│   ├── code_analysis.py       # 代码分析
│   ├── code_modification.py   # 代码修改
│   ├── debug_control.py       # 调试控制
│   ├── information.py         # 信息获取
│   ├── advanced.py            # 高级功能
│   ├── utility.py             # 实用工具（组合模块）
│   ├── utility_bookmark.py    # 书签操作
│   └── utility_management.py  # 管理功能（文件/脚本/配置）
├── registry/                  # 工具注册模块
│   └── tool_registry.py       # MCP工具注册
├── utils/                     # 共享工具模块
│   └── address_utils.py       # 地址工具函数
└── x64dbg_controller.py       # 主控制器（整合所有模块）
```

### 设计原则

1. **单一职责**：每个模块只负责一个功能领域
2. **文件大小限制**：每个文件不超过200行（部分组合模块除外）
3. **组合模式**：使用组合而非继承，便于扩展和维护
4. **向后兼容**：保持原有接口不变，确保现有代码正常工作

### 模块说明

- **core/**：提供基础功能，所有模块都依赖这些核心组件
- **modules/**：功能模块，每个模块封装一类相关功能
- **registry/**：负责将功能模块注册为MCP工具
- **utils/**：提供通用的工具函数，供各模块使用

## 可用工具

<details>
<summary>点击展开查看所有可用工具（共88个工具）</summary>

### x64dbg_execute_command
执行任意x64dbg调试命令

### x64dbg_get_registers
获取当前所有寄存器值

### x64dbg_get_modules
获取已加载的模块列表

### x64dbg_set_breakpoint
在指定地址设置断点

### x64dbg_remove_breakpoint
删除指定地址的断点

### x64dbg_read_memory
读取指定地址的内存内容

### x64dbg_write_memory
向指定地址写入内存数据

### x64dbg_disassemble
反汇编指定地址的代码

### x64dbg_step_over
单步执行（跳过函数调用）

### x64dbg_step_into
单步进入（进入函数调用）

### x64dbg_continue
继续执行程序

### x64dbg_pause
暂停程序执行

### x64dbg_get_stack
获取当前堆栈信息

### x64dbg_search_memory
在内存中搜索指定模式

### x64dbg_get_debugger_status
获取调试器实时状态（是否调试中、运行状态、当前PID/TID、地址等）

### x64dbg_set_breakpoint_conditional
设置带条件的断点（例如：当eax==0x100时触发）

### x64dbg_dump_memory
将内存转储到文件（支持最大10MB）

### x64dbg_resolve_symbol
解析符号名称到内存地址（例如：MessageBoxA, kernel32.CreateFile）

### x64dbg_get_threads
获取线程列表

### x64dbg_get_breakpoints
获取所有断点列表

### x64dbg_get_call_stack
获取调用栈信息

### x64dbg_get_segments
获取内存段信息

### x64dbg_get_strings
搜索字符串引用

### x64dbg_get_references
获取地址的交叉引用

### x64dbg_get_imports
获取导入函数列表

### x64dbg_get_exports
获取导出函数列表

### x64dbg_get_comments
获取注释信息

### x64dbg_get_labels
获取标签列表

### x64dbg_get_functions
获取函数列表

### x64dbg_enable_breakpoint
启用断点（如果断点被禁用）

### x64dbg_disable_breakpoint
禁用断点（不断点删除，只是临时禁用）

### x64dbg_capture_output
捕获命令执行的实际输出（增强版命令执行，包含输出解析）

### x64dbg_get_logs
获取x64dbg日志输出

### x64dbg_set_memory_protection
设置内存保护属性（可读、可写、可执行等）

### x64dbg_get_memory_protection
获取内存保护属性

### x64dbg_set_hardware_breakpoint
设置硬件断点（支持执行、写入、读取、读写断点）

### x64dbg_remove_hardware_breakpoint
删除硬件断点

### x64dbg_set_watchpoint
设置数据断点（监视点），用于监控内存访问

### x64dbg_remove_watchpoint
删除数据断点（监视点）

### x64dbg_attach_process
附加到正在运行的进程进行调试

### x64dbg_detach_process
分离当前调试的进程（不断点终止进程）

### x64dbg_apply_patch
应用代码补丁（修改代码）

### x64dbg_remove_patch
移除代码补丁（恢复原始代码）

### x64dbg_get_patches
获取所有补丁列表

### x64dbg_inject_code
注入代码（Shellcode）到目标进程

### x64dbg_inject_dll
注入DLL到目标进程

### x64dbg_eject_dll
卸载DLL（从目标进程中移除）

### x64dbg_bypass_antidebug
绕过反调试检测（修改PEB标志、绕过NtQuery等）

### x64dbg_set_exception_handler
设置异常处理（忽略/中断/记录特定异常）

### x64dbg_get_exception_info
获取当前异常信息

### x64dbg_load_file
加载文件到调试器

### x64dbg_save_memory_to_file
保存内存到文件

### x64dbg_compare_memory
比较两处内存内容（查找差异）

### x64dbg_fill_memory
填充内存（用指定值填充内存区域）

### x64dbg_calculate_address
计算地址（基址+偏移）

### x64dbg_format_address
格式化地址（十六进制/十进制转换）

### x64dbg_set_register
设置单个寄存器值

### x64dbg_set_registers
批量设置寄存器值

### x64dbg_get_breakpoint_hit_count
获取断点命中计数（断点被触发的次数）

### x64dbg_reset_breakpoint_hit_count
重置断点命中计数

### x64dbg_add_bookmark
添加地址书签

### x64dbg_remove_bookmark
删除地址书签

### x64dbg_get_bookmarks
获取所有书签列表

### x64dbg_goto_bookmark
跳转到书签地址

### x64dbg_switch_thread
切换当前线程

### x64dbg_suspend_thread
挂起线程

### x64dbg_resume_thread
恢复线程

### x64dbg_get_thread_context
获取线程上下文

### x64dbg_start_trace
开始执行跟踪

### x64dbg_stop_trace
停止执行跟踪

### x64dbg_get_trace_records
获取跟踪记录

### x64dbg_allocate_memory
在目标进程中分配内存

### x64dbg_free_memory
释放分配的内存

### x64dbg_get_memory_region_info
获取内存区域信息

### x64dbg_evaluate_expression
计算表达式（支持寄存器、内存地址、常量等）

### x64dbg_batch_set_breakpoints
批量设置断点

### x64dbg_batch_remove_breakpoints
批量删除断点

### x64dbg_batch_read_memory
批量读取内存

### x64dbg_view_structure
查看结构体数据（PEB、TEB等）

### x64dbg_save_script
保存脚本到文件

### x64dbg_load_script
从文件加载脚本

### x64dbg_get_script_history
获取脚本执行历史

### x64dbg_save_config
保存当前调试配置

### x64dbg_load_config
加载调试配置

### x64dbg_list_configs
获取所有配置列表

### x64dbg_start_profiling
开始性能分析

### x64dbg_stop_profiling
停止性能分析

### x64dbg_get_profiling_results
获取性能分析结果

</details>

## 注意事项

1. **x64dbg必须已安装**：确保x64dbg已正确安装并配置路径
2. **Python插件**：x64dbg需要支持Python插件（通常自带）
3. **权限问题**：确保有权限在x64dbg插件目录创建文件
4. **自动执行**：新版本支持自动执行脚本，如果x64dbg正在运行且支持API，命令会自动执行
5. **手动操作**：如果自动执行失败，某些操作可能需要手动在x64dbg中加载脚本文件
6. **调试模式**：建议在调试模式下使用，查看详细日志
7. **Cursor版本**：确保使用支持MCP的Cursor版本（通常需要较新版本）
8. **结果解析**：新版本支持自动解析脚本执行结果，获取实际输出内容

## 故障排除

<details>
<summary>点击展开查看故障排除指南</summary>

### 问题：找不到x64dbg路径

**解决方案**：
1. 检查 `config.py` 中的路径配置
2. 确保x64dbg已正确安装
3. 手动设置正确的路径

### 问题：无法创建脚本文件

**解决方案**：
1. 检查x64dbg插件目录的写入权限
2. 确保目录存在
3. 检查磁盘空间

### 问题：命令执行失败

**解决方案**：
1. 确保x64dbg已启动并加载了目标程序
2. 检查命令语法是否正确
3. 查看x64dbg的日志输出

### 问题：Cursor中MCP服务器未显示

**解决方案**：
1. 检查 `mcp.json` 文件格式是否正确（JSON格式）
2. 确认文件路径正确（项目级：`.cursor/mcp.json`，全局级：用户配置目录）
3. 重启Cursor IDE
4. 检查Cursor设置中的MCP功能是否已启用
5. 查看Cursor的输出面板（`View` > `Output`）查看MCP相关错误信息

### 问题：Python路径错误

**解决方案**：
1. 确保Python已正确安装并在PATH中
2. 使用完整路径指定Python解释器：
   ```json
   {
     "mcpServers": {
       "x64dbg-mcp": {
         "command": "C:\\Python\\python.exe",
         "args": ["${workspaceFolder}/main.py"]
       }
     }
   }
   ```
3. 如果使用虚拟环境，确保激活虚拟环境或使用虚拟环境的Python路径

</details>

## 更新日志

查看完整的提交历史：[Git提交记录](https://github.com/baiyajin/x64dbg-mcp/commits/main)

<details>
<summary>点击展开查看最近更新</summary>

- ✅ **docs: 移除已完成的开发计划部分** - 清理README，移除已完成的功能列表
- ✅ **chore: 优化FastMCP日志输出配置** - 减少日志输出，优化启动体验
- ✅ **feat: 添加智能x64dbg路径检测** - 支持自动检测x64dbg安装路径，未安装时提供友好提示
- ✅ **docs: 在README中添加项目logo** - 添加项目logo展示
- ✅ **修复: 解决异常消息中的中文乱码问题** - 修复编码问题，确保中文正确显示
- ✅ **修复: 解决日志乱码问题** - 配置UTF-8编码，解决日志输出乱码
- ✅ **修复: 解决MCP协议JSON解析错误问题** - 修复f-string语法错误
- ✅ **重构: 拆分大文件使其符合200行限制** - 模块化重构，遵循单一职责原则
- ✅ **配置: 添加Cursor MCP服务器配置文件** - 添加MCP服务器配置示例

</details>

## 许可证

本项目采用MIT许可证。

## 贡献

欢迎提交Issue和Pull Request！

## 支持项目

如果这个项目对你有帮助，欢迎通过微信赞赏支持开发者继续改进项目！

<div align="center">
  <img src="wechat_reward.jpg" alt="微信赞赏码" width="300">
  <p><em>你的鼓励是我改BUG的动力 💪</em></p>
</div>

## 技术支持

遇到问题需要帮助？欢迎加入付费技术支持咨询交流QQ群，与开发者和其他用户交流！

<div align="center">
  <img src="qq_group.jpg" alt="付费技术支持咨询交流QQ群" width="300">
  <p><em>扫码加入QQ群，获取技术支持 💬</em></p>
</div>

## 相关链接

- [x64dbg官网](https://x64dbg.com/)
- [Model Context Protocol文档](https://modelcontextprotocol.io/)
- [FastMCP文档](https://github.com/jlowin/fastmcp)
- [Cursor MCP文档](https://docs.cursor.com/context/mcp)
- [Git提交历史](https://github.com/baiyajin/x64dbg-mcp/commits/main)
- [GitHub仓库](https://github.com/baiyajin/x64dbg-mcp)