Ida Multi MCP

🚀 ida-multi-mcp

ida-multi-mcp 是一个多实例 IDA Pro MCP 服务器，可通过单个 MCP 端点同时对多个二进制文件进行逆向工程。借助该工具，用户能够使用 IDA Pro 并行分析多个二进制文件，所有实例均可通过单一 MCP 连接访问，无需为每个实例单独配置 MCP 客户端。

🚀 快速开始

ida-multi-mcp 允许你使用 IDA Pro 并行分析多个二进制文件，所有实例都可以通过一个 MCP 连接访问。你只需打开多个 IDA 实例，服务器会自动发现并将请求路由到每个实例，而无需管理多个 MCP 客户端配置。

MCP Client (Claude, Cursor, etc.)
    │  stdio (MCP Protocol)
    ▼
┌─────────────────────────────────┐
│  ida-multi-mcp Server (Router)  │
│  - 动态工具发现                 │
│  - 注入 instance_id             │
│  - 管理工具                     │
└───┬──────┬──────┬───────────────┘
    │      │      │  HTTP JSON-RPC
    ▼      ▼      ▼
  IDA #1  IDA #2  IDA #3
  (自动)  (自动)  (自动)

✨ 主要特性

• 零配置实例发现：每个 IDA Pro 实例在启动时自动注册。
• 无端口冲突：使用操作系统自动分配的端口（端口 0）。
• 动态工具发现：所有 71 种以上的 IDA 工具可自动使用。
• 跨二进制分析：通过 instance_id 参数指定特定实例。
• 智能实例跟踪：使用 4 字符 ID（如 k7m2、px3a 等），并自动检测二进制文件的更改。
• 基于文件的注册表：跟踪所有活动实例。
• 优雅回退：处理二进制文件更改、过时实例和崩溃情况。

📦 安装指南

手动安装

macOS

⚠️ 重要提示

IDA Pro 通常使用与系统默认不同的 Python 版本（例如，IDA 使用 Python 3.11，而 macOS 自带 3.14）。你必须为终端 Python 和 IDA 的 Python 都安装该软件包。

步骤 1：检查 IDA 的 Python 版本

打开 IDA Pro，然后在 IDA 控制台中运行：

Python> import sys; print(sys.version)

记录版本号（例如 3.11）。

步骤 2：安装

# 1. 通过 pipx 安装 CLI 工具（用于终端命令）
pipx install git+https://github.com/MeroZemory/ida-multi-mcp.git

# 2. 为 IDA 的 Python 安装软件包（将 3.11 替换为你的 IDA 版本）
python3.11 -m pip install --user git+https://github.com/MeroZemory/ida-multi-mcp.git

# 3. 安装 IDA 插件并配置 MCP 客户端
ida-multi-mcp --install

# 4. 手动配置 Claude Code（对于 Claude Code，建议使用此方法而非 --install）
claude mcp add ida-multi-mcp -s user -- ida-multi-mcp

💡 使用建议

ida-multi-mcp --install 使用 python3 -m ida_multi_mcp 注册 MCP 服务器，这在 macOS 上可能指向错误的 Python 版本。对于 Claude Code，请使用上面显示的 claude mcp add 以确保它直接使用 pipx 管理的 CLI。

Windows

# 0. （建议）清理以前的安装，以避免残留脚本/配置
ida-multi-mcp --uninstall
python -m pip uninstall -y ida-multi-mcp

# 1. 安装 ida-multi-mcp
python -m pip install git+https://github.com/MeroZemory/ida-multi-mcp.git

# 2. 安装 IDA 插件并配置所有 MCP 客户端
ida-multi-mcp --install

💡 使用建议

如果 IDA 使用的 Python 版本与默认版本不同，请使用 py -3.12（替换为 IDA 的版本）而不是 python。如果你手动编辑 %USERPROFILE%\\.codex\\config.toml，请对 Windows 路径使用字面量 TOML 引用（例如 [projects.'\\?\\C:\\path\\to\\repo']，command = 'C:\\...\\python.exe'）。

Linux

# 1. 安装 ida-multi-mcp
pip install --user git+https://github.com/MeroZemory/ida-multi-mcp.git

# 2. 安装 IDA 插件并配置 MCP 客户端
ida-multi-mcp --install

AI 代理安装

获取并遵循安装指南：

curl -s https://raw.githubusercontent.com/MeroZemory/ida-multi-mcp/main/docs/installation.md

该指南涵盖：

1. 特定平台的软件包安装（macOS、Windows、Linux）
2. 匹配 IDA Python 版本
3. IDA 插件设置和 MCP 客户端自动配置 (ida-multi-mcp --install)
4. 验证和故障排除

支持的 MCP 客户端

可与任何 MCP 兼容的客户端配合使用。已测试的客户端包括：

MCP 客户端配置

ida-multi-mcp --install 会自动配置所有检测到的 MCP 客户端，包括 Claude Code、Claude Desktop、Cursor、Windsurf、VS Code、Zed 等 20 多种。

对于未自动检测到的客户端或查看配置 JSON，请运行：

ida-multi-mcp --config

💻 使用示例

打开多个二进制文件

1. 打开 IDA Pro 并加载第一个二进制文件（例如 malware.exe）

   • 插件会自动加载（PLUGIN_FIX 标志）
   • 实例会自动注册并获得一个 4 字符 ID（例如 k7m2）

2. 打开另一个 IDA Pro 实例并加载第二个二进制文件（例如 dropper.dll）

   • 另一个实例会自动注册（例如 px3a）

3. 重复上述步骤以处理更多二进制文件

查看已注册的实例

ida-multi-mcp --list

输出示例：

已注册的 IDA 实例 (3):

  k7m2
    二进制文件: malware.exe
    路径: C:/samples/malware.exe
    架构: x86_64
    端口: 49152
    PID: 12345

  px3a
    二进制文件: dropper.dll
    路径: C:/samples/dropper.dll
    架构: x86_64
    端口: 49153
    PID: 12346

  9bf1
    二进制文件: payload.exe
    路径: C:/samples/payload.exe
    架构: x86
    端口: 49154
    PID: 12347

在大语言模型中使用

连接后，所有 71 种以上的 IDA 工具均可使用。所有 IDA 工具调用都需要 instance_id 参数，以避免跨代理冲突。

分析单个实例：

反编译 malware.exe (k7m2) 中的主函数

跨二进制分析：

反编译 malware.exe (k7m2) 中的 main 函数，并将其与 dropper.dll (px3a) 中的入口点进行比较

📚 详细文档

管理工具

服务器提供了内置的管理工具：

list_instances()

列出所有已注册的 IDA 实例及其元数据（二进制文件名、路径、架构、端口）。

refresh_tools()

从 IDA 实例重新发现工具。如果更新了 IDA 插件，请使用此功能。

get_cached_output(cache_id: str, offset: int = 0, size: int = 20000)

检索之前工具调用的缓存输出（如果输出被截断）。

decompile_to_file(...)

反编译函数并将结果直接保存到磁盘文件。需要 instance_id 参数。

实例 ID 解释

实例 ID 是 4 字符的 base36 字符串（0 - 9，a - z），如 k7m2、px3a、9bf1。

为什么是 4 个字符？

• 简短易读
• 有 168 万种组合（在典型使用中无冲突）
• 如果检测到冲突，会自动扩展到 5 个字符

它们是如何生成的？

• 基于进程 ID、端口和 IDB 文件路径生成
• 重新打开相同的二进制文件会得到相同的 ID（确定性）
• 替换/更改二进制文件会生成新的 ID（自动）

更改二进制文件时会发生什么？ 当你在 IDA 实例中打开不同的二进制文件时：

1. 旧实例过期（例如 k7m2 → 过期）
2. 新实例注册（例如 b12）
3. 如果大语言模型尝试使用旧 ID，会收到一个包含替换 ID 的有用错误信息

CLI 命令

ida-multi-mcp

启动 MCP 服务器（标准输入输出）。供 MCP 客户端使用。这是默认命令。

ida-multi-mcp

ida-multi-mcp --list

列出所有已注册的 IDA 实例。

ida-multi-mcp --list

ida-multi-mcp --install [--ida-dir DIR]

安装 IDA 插件并自动配置所有检测到的 MCP 客户端（Claude Code、Claude Desktop、Cursor、Windsurf、VS Code、Zed 等 20 多种）。

ida-multi-mcp --install
ida-multi-mcp --install --ida-dir "C:\Program Files\IDA Pro 9.0"  # Windows 自定义路径

ida-multi-mcp --uninstall [--ida-dir DIR]

移除 IDA 插件，清理注册表，并移除 MCP 客户端配置。

ida-multi-mcp --uninstall

ida-multi-mcp --config

打印 MCP 客户端配置 JSON，方便参考。

ida-multi-mcp --config

架构

实例注册表

位置：

• macOS/Linux: ~/.ida-mcp/instances.json
• Windows: %USERPROFILE%\.ida-mcp\instances.json

每个注册实例包含以下信息：

• id：4 字符实例标识符（如 k7m2、px3a 等）
• pid：IDA Pro 实例的进程 ID
• host：始终为 127.0.0.1（本地主机）
• port：动态分配的 HTTP 端口
• binary_name：文件名（如 malware.exe、driver.dll 等）
• binary_path：二进制文件的完整路径
• arch：架构（如 x86_64、x86、arm64 等）
• registered_at：实例注册的时间戳
• last_heartbeat：最后一次心跳检查的时间戳

IDA 插件目录

• macOS/Linux: ~/.idapro/plugins/
• Windows: %APPDATA%\Hex-Rays\IDA Pro\plugins\

请求路由

1. MCP 客户端调用工具（例如 decompile）并提供所需的 instance_id 参数
2. 服务器通过 HTTP JSON-RPC 将请求路由到目标实例
3. IDA 实例处理请求
4. 结果返回给客户端

健康监测

• 每个 IDA 实例每 60 秒发送一次心跳
• 过时的实例（2 分钟以上无心跳）会自动清理
• 服务器启动时，会从注册表中移除已死亡的进程
• 如果实例崩溃，后续请求会收到有用的错误信息

二进制文件更改检测

使用双重策略检测：

主要（快速）：当二进制文件更改时，IDA 事件钩子会立即触发 备用（安全）：每次工具调用都会验证二进制文件是否更改，以处理钩子失败的情况

当检测到二进制文件更改时：

• 旧实例 ID 标记为过期
• 新实例使用新 ID 注册
• 大语言模型会收到包含替换 ID 的有用消息

故障排除

"No IDA instances registered"

确保：

1. IDA Pro 正在运行并加载了二进制文件
2. 检查 IDA 的插件列表（编辑 → 插件 → 扫描）以确认 ida-multi-mcp 插件已加载
3. 检查 IDA 控制台是否有错误消息
4. 再次运行 ida-multi-mcp --list

"Instance 'k7m2' not found"

该实例已崩溃或过期。运行：

ida-multi-mcp --list

查看可用实例，然后使用有效的 ID。

"Instance 'k7m2' expired. Replaced by 'px3a'"

你在该 IDA 实例中打开了不同的二进制文件。这是正常现象。使用新的实例 ID (px3a)。

插件未在 IDA 中加载 / "No module named 'ida_multi_mcp'"

这通常意味着 IDA 的 Python 由于 Python 版本不匹配 而找不到该软件包。

1. 检查 IDA 的 Python 版本 — 在 IDA 控制台中运行：

   import sys; print(sys.version)
   

2. 为该特定 Python 版本安装软件包：

   macOS:

   # 将 3.11 替换为 IDA 的实际 Python 版本
   python3.11 -m pip install --user git+https://github.com/MeroZemory/ida-multi-mcp.git
   

   Windows:

   # 将 3.12 替换为 IDA 的实际 Python 版本
   py -3.12 -m pip install git+https://github.com/MeroZemory/ida-multi-mcp.git
   

3. 确保 IDA 插件目录包含 ida_multi_mcp.py：

   • macOS/Linux: ~/.idapro/plugins/
   • Windows: %APPDATA%\Hex-Rays\IDA Pro\plugins\

4. 重启 IDA Pro

MCP 服务器连接失败（macOS）

如果你的 MCP 客户端显示 Status: failed 表示 ida-multi-mcp 连接失败，注册的命令可能指向错误的 Python 版本。

1. 检查配置的命令（例如，在 .claude.json、.cursor/mcp.json 中）

2. 如果显示 python3 -m ida_multi_mcp，将其替换为 pipx 管理的 CLI：

   Claude Code:

   claude mcp remove ida-multi-mcp -s user
   claude mcp add ida-multi-mcp -s user -- ida-multi-mcp
   

   其他客户端： 编辑 MCP 配置 JSON 并更改：

   {
     "command": "ida-multi-mcp",
     "args": []
   }
   

3. 重启 MCP 客户端

Codex 在 Windows 上启动失败并出现 TOML 解析错误

如果 Codex 打印类似 invalid unquoted key 的错误信息，对于 %USERPROFILE%\.codex\config.toml，配置中包含的 Windows 路径不是有效的 TOML 语法。

对 Windows 路径使用字面量引用的键/字符串：

[projects.'\\?\C:\Git\MeroZemory\tidy-up']
trust_level = "trusted"

[mcp_servers.ida-multi-mcp]
command = 'C:\Users\MeroZemory\AppData\Local\Programs\Python\Python311\python.exe'
args = ["-m", "ida_multi_mcp"]

不要使用未引用的 \\?\... 项目表键，并且除非反斜杠已转义，否则不要使用双引号的 Windows 路径。

设计决策

性能

• 注册表操作：<1ms（JSON 文件，文件锁定）
• 工具发现：每个 IDA 实例约 50ms（一次性缓存）
• 工具调用路由：<5ms（本地 HTTP JSON-RPC）
• 心跳间隔：60 秒（开销可忽略不计）

限制

• 仅支持 127.0.0.1（本地分析）
• v1.0 不支持远程 IDA 实例
• 目前不支持 IDA 批处理/无头（idalib）模式
• v1.0 中资源（非工具）需要手动路由

📄 许可证

本项目采用 MIT 许可证。

贡献说明

欢迎贡献代码！请确保：

• 代码与 Python 3.11+ 兼容
• 支持跨平台（Windows、macOS、Linux）
• 代码简洁易读
• 为新功能添加测试

致谢

本项目受到 ida-pro-mcp 的启发并基于其构建，该项目由 Duncan Ogilvie (mrexodia) 开发。IDA 工具的实现（71 种以上的工具）源自 ida-pro-mcp，并已作为捆绑包集成到 ida-multi-mcp 中，在此基础上增加了多实例编排功能。

安装方法（对 AI 代理友好的安装指南）受到 oh-my-opencode 的影响，该项目由 Yeongyu Yun (code-yeongyu) 开发。

相关项目

• ida-pro-mcp：原始的单实例 IDA MCP 插件（工具源自此处）（MIT 许可证）
• Claude Code：原生支持 MCP 的客户端
• Cursor：支持 MCP 的替代编辑器

支持

如果你遇到问题、有功能请求或疑问，请：

• 查看上面的故障排除部分
• 查看 DESIGN.md 了解架构细节
• 在 GitHub 上提交问题