my-ida-mcp —— 生产级 IDA Pro MCP 增强服务

让大语言模型（Claude、Cursor、Cline、ZCode、Codex 等）真正掌控 IDA Pro。
免除逆向幻觉，AI 直接远程调用 Hex-Rays 反编译、查看与修改汇编、重构结构体与类型、追踪交叉引用、读写内存、并直接驱动动态调试器！

🌟 核心更新与增强特性（为什么选择此分支？）

本仓库基于上游官方 mrexodia/ida-pro-mcp 开发主线，针对逆向工程生产环境的痛点进行了深度重构与加固，完整吸收并合并了社区 14 项高价值核心 PR，解决了原版在大二进制卡顿、结构体篡改错位、JSON-RPC 偶发崩溃及端口冲突等一系列顽疾：

1. 端口隔离与连接永续（本地生产加固）

• 固化避让端口 13437：原版默认端口 13337 极易与后台常驻无头服务或其他工具冲突；当端口冲突时，原版会自动漂移到 13338，导致外部 AI 客户端（配置了固定 URL）瞬间断联。本项目彻底将默认端口固化为 13437，实现 GUI 与后台的稳定物理隔离。

• 默认开启全量 88 工具：服务端挂载 ?ext=dbg 扩展，默认暴露全套 88 个工具（包含 22 个完整的动态调试器 dbg_* 工具）。

2. 海量符号流式查询，毫秒级响应（PR #484）

• 彻底根治分页假死：原版的 list_funcs、func_query、entity_query 在分页（如 count=50）时，底层会先全量遍历整个程序的数万个函数生成大列表再切片。面对几十 MB 的大型游戏/DLL 会直接导致 IDA 假死 20~30 秒甚至 OOM。

• 流式惰性扫描：全面重构为 Lazy Stream，分页达到目标数量立即截断返回，耗时骤降至毫秒级，大型二进制分析丝滑流畅。

3. C 头文件直接批量导入（PR #544）

• 新增 import_type_header(paths) 工具：支持将现成的本地 C 头文件（.h）直接批量导入当前 IDB 的 Local Types（本地类型库），无需再逐个拼接字符串调用 declare_type，一键载入整份 SDK。

4. 结构体增量逆向不偏位（PR #473）

• 新增 struct_member_upsert 工具：逆向 C++ 虚表或复杂数据结构时，支持按指定的字节偏移（Offset）精准填补空隙（gapNN）或替换成员，绝对不会挤偏后续字段的内存对齐和偏移。

5. 动静结合基址映射（PR #451）

• 新增基址重定位与地址转换工具：支持运行时动态地址（如 Cheat Engine / x64dbg 抓到的 ASLR 内存地址）与 IDA 静态反汇编地址的双向映射转换与重定位，动静结合逆向零算错。

6. 反混淆微指令修复（PR #500）

• 暴露 ignore_micro 并增 set_ignore_micro 工具：修复 Hex-Rays 在反编译某些手写汇编或花指令混淆时，误将关键指令视为空操作 NOP 导致反编译代码失真的问题。

7. 严密防崩溃与大模型参数容错（PR #541, #537, #543）

• stdio 代理防崩保护（#541）：当遇到畸形请求时，不再崩溃断联，而是规范回包 JSON-RPC -32600 Invalid Request。

• 自动反序列化嵌套字符串（#537）：彻底解决大模型偶发将字典/数组参数错误格式化为 JSON 字符串导致的校验报错。

• 空批次保持为空（#543）：修复空 batch 转为幽灵空查询引发的异常。

• Keep-Alive 退出秒级响应（#527）：修复长连接闲置时 stop() 阻塞等待 30 秒超时的问题。

8. 更多逆向增强

• PR #469：新增 organize_functions 工具，支持按文件夹树结构整理归档函数列表。

• PR #475：无头模式及 stdio 通道完整支持动态调试器扩展。

• PR #501 & #542：支持无头 worker 空闲超时配置，并修复 profile 模式下退出静默丢失 IDB 修改的问题。

• PR #463：完善 Codex 项目范围安装器。

Related MCP server: IDAssistMCP

📋 运行前准备（Prerequisites）

1. Python 环境：Python 3.11 及以上（推荐 Python 3.12 ~ 3.14）。

   • 需使用 IDA 自带的 idapyswitch 工具将 IDA 关联到该 Python 版本。

2. IDA Pro：IDA Pro 8.3 及以上（推荐 9.x / 9.5），不支持 IDA Free。

3. 激活全局 idalib（无头模式及部分 Python 依赖必需）：

   # Windows 示例（将路径替换为实际 IDA 安装目录）
   uv run "<IDA_INSTALL_DIR>\idalib\python\py-activate-idalib.py"
   
   # Linux / macOS 示例
   uv run "/path/to/idapro/idalib/python/py-activate-idalib.py"

🚀 安装部署（Installation）

方式一：直接通过 pip 安装（推荐）

pip install git+https://github.com/zhengwuji/my-ida-mcp.git

方式二：克隆本地源码安装

git clone https://github.com/zhengwuji/my-ida-mcp.git
cd my-ida-mcp
pip install -e .

刷新 / 安装 IDA 插件

在终端中执行以下命令，将插件部署到 IDA 插件目录：

ida-pro-mcp --install

💡 如何在 IDA 中使用

1. GUI 交互模式（最常用、最推荐）：

   • 打开 IDA Pro 并加载任意待分析的二进制文件。

   • 插件会自动启动 MCP 服务（默认端口 13437）。

   • 在 IDA 的 Output 窗口将看到如下就绪日志：

     [MCP] Autostarting server...
       Config: http://127.0.0.1:13437/config.html
     [MCP] Registered instance: target.exe (pid=..., port=13437)

   • 快捷键：Ctrl+Alt+M 可随时手动启停或重载 MCP 服务。

   • 菜单栏：通过 Edit → Plugins → MCP Configuration 可按 IDB 独立调整配置。

2. 无头 idalib 模式（命令行批量分析）：

   • 运行命令：idalib-mcp

   • 详见项目内部脚本与无头服务参数。

🤖 AI 客户端接入配置（Client Setup）

在支持 MCP 的客户端配置文件中，添加如下服务定义（支持全套 88 工具）：

1. 通用 HTTP 配置（Claude Desktop / Cursor / Windsurf / Cline / Roo Code / ZCode）

{
  "mcpServers": {
    "ida-pro-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:13437/mcp?ext=dbg"
    }
  }
}

各客户端配置文件常见位置：

• Cursor / Windsurf：设置中 MCP 服务器列表添加 HTTP URL 即可。

• Claude Desktop：%APPDATA%\Claude\claude_desktop_config.json

• Claude Code：~/.claude.json 顶层 mcpServers

• ZCode：~/.zcode/cli/config.json

🎯 AI Agent 调用黄金四法则（防踩坑必读）

为确保大语言模型在调用 IDA-MCP 时拥有 100% 的成功率，建议在 System Prompt 中加入以下规范：

1. 【GUI 模式严禁传 database 参数】

   • 本机 GUI 模式会自动承接当前 IDA 窗口打开的数据库。绝不要在请求中附加 database 参数，否则会导致参数异常。

2. 【查询参数严禁平铺，必须传 JSON 数组】

   • list_funcs、list_globals、func_query、entity_query 等查询工具的参数必须是 queries 列表对象：

     • ❌ 错误：{"offset": 0, "count": 50}

     • ✅ 正确：{"queries": [{"offset": 0, "count": 50}]}

   • imports 工具两个参数均必填：{"offset": 0, "count": 0}（count=0 代表全量获取）。

3. 【符号事实第一，禁止脑补】

   • 严禁凭语料记忆瞎猜函数名。必须先调用 survey_binary 或 list_funcs 获取目标程序中真实存在的符号或十六进制地址（如 0x140001000），再发起 decompile。

4. 【标准分析流程】：

   • server_health 探活 ➔ survey_binary 宏观架构 ➔ find_regex/imports 关键线索 ➔ decompile 伪代码 ➔ xrefs_to 调用链 ➔ rename/set_comments 回写 IDB ➔ dbg_* 动态调试。

🛠️ 核心工具分类速查（共 88 项）

📄 开源许可

本项目遵循 MIT License 开源协议。 原始项目版权归原作者 mrexodia 及广大开源贡献者所有。