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

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.11%2B-green.svg)](https://python.org)
[![IDA Pro](https://img.shields.io/badge/IDA%20Pro-8.3%20|%209.x-orange.svg)](https://hex-rays.com/ida-pro)
[![Tools](https://img.shields.io/badge/MCP%20Tools-88-brightgreen.svg)](#)

> **让大语言模型（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 项目范围安装器。

---

## 📋 运行前准备（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 依赖必需）：
   ```powershell
   # 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 安装（推荐）

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

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

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

### 刷新 / 安装 IDA 插件

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

```bash
ida-pro-mcp --install
```

---

## 💡 如何在 IDA 中使用

1. **GUI 交互模式（最常用、最推荐）**：
   * 打开 IDA Pro 并加载任意待分析的二进制文件。
   * 插件会自动启动 MCP 服务（默认端口 **`13437`**）。
   * 在 IDA 的 Output 窗口将看到如下就绪日志：
     ```text
     [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）

```json
{
  "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 项）

| 模块分类 | 数量 | 代表工具 | 说明 |
|---|---|---|---|
| **会话与概况** | 3 | `survey_binary`, `server_health`, `idb_save` | 探活、获取架构/段/Top热门函数 |
| **符号与列表** | 12 | `lookup_funcs`, `list_funcs`, `imports`, `find_regex` | 流式极速枚举函数、导入表与字符串 |
| **反编译与分析** | 14 | `decompile`, `disasm`, `xrefs_to`, `callgraph` | Hex-Rays 伪代码反编译、指令反汇编、交叉引用追踪 |
| **组合分析** | 4 | `analyze_function`, `analyze_component`, `diff_before_after` | 单函数全量体检、改名前后伪代码对比 |
| **内存与打补丁** | 17 | `get_bytes`, `patch`, `patch_asm`, `rename`, `set_comments` | 读写内存字节、汇编级补丁、批量改名、反编译注释双向同步 |
| **类型与结构体** | 9 | `import_type_header`, `struct_member_upsert`, `declare_type` | **C头文件批量导入**、**按Offset填补结构体空隙**、类型定义 |
| **特征码签名** | 4 | `make_signature`, `find_xref_signatures` | 自动提取最短唯一特征码 |
| **Python 后门** | 2 | `py_eval`, `py_exec_file` | 在 IDA 内部执行任意 Python 脚本 |
| **动态调试器** | 22 | `dbg_start`, `dbg_add_bp`, `dbg_regs`, `dbg_step_over`, `dbg_read` | 完整的动态调试、下断点、读写寄存器与单步步进 |

---

## 📄 开源许可

本项目遵循 [MIT License](LICENSE) 开源协议。
原始项目版权归原作者 [mrexodia](https://github.com/mrexodia/ida-pro-mcp) 及广大开源贡献者所有。