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依赖

pip install -r requirements.txt

或使用uv（推荐）：

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，修改以下行：

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

例如：

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:

$env:X64DBG_PATH = "D:\baiyajin-code\x64dbg\release\x64\x64dbg.exe"

Windows 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 文件夹（如果不存在）：

   mkdir .cursor
   

2. 创建MCP配置文件

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

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

   使用uv（推荐）：

   {
     "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 文件，添加以下配置（请将路径替换为你的实际项目路径）：

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

   使用uv（推荐）：

   {
     "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服务器配置：

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

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

{
  "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解释器：

   {
     "mcpServers": {
       "x64dbg-mcp": {
         "command": "C:\\Python\\python.exe",
         "args": ["${workspaceFolder}/main.py"]
       }
     }
   }
   

3. 如果使用虚拟环境，确保激活虚拟环境或使用虚拟环境的Python路径

</details>

更新日志

查看完整的提交历史：Git提交记录

<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官网
• Model Context Protocol文档
• FastMCP文档
• Cursor MCP文档
• Git提交历史
• GitHub仓库