IDA Pro MCP Fusion

 

一个 MCP 端点。多个二进制文件。持久化分析上下文。

快速开始 · Fusion 的优势 · 架构 · 工具 · 配置 · 开发

Fusion 是什么？

IDA Pro MCP Fusion 将兼容 MCP 的编码 Agent 连接到 IDA Pro，并将单个连接转变为实用的逆向工程工作区。它结合了实时 IDA 分析、持久化 SQLite 索引，以及一个可在隔离的无头工作进程中同时打开多个二进制文件的监管器。

可用它反编译和反汇编函数、追踪交叉引用、查询类型、重命名符号、修补数据、创建签名、检查多个样本，并重复利用缓存的分析结果，而不必反复调用 IDA 的单线程 API。

重要

此项目需要本地安装并获得许可的 IDA Pro。不支持 IDA Free。此服务不提供 IDA、Hex-Rays 或托管分析服务。

Fusion 的优势

	功能	带来的改变
⚡	持久化 SQLite 缓存	函数、字符串、全局变量、导入项、交叉引用和调用图边在重复调查期间都可供查询。
◈	多二进制文件监管器	通过一个 MCP 端点打开、定位并关闭多个 GUI 或无头数据库。
⛓	持久化工作进程	后续启动的监管器可以发现并接管同一数据库的现有工作进程。
◎	批处理优先的工作流	通过一次 idb_batch_open 调用，为一组样本预热分析并构建缓存。
⛨	受控功能范围	只读配置文件、选择启用的不安全工具、工作进程数量限制、超时和空闲清理，让自动化保持在受控范围内。

缓存与 IDB 文件存放在一起，文件名为 <database>.mcp.sqlite。系统会根据 IDB 修改时间和缓存架构检查缓存是否为最新，因此不会静默复用过期记录。

快速开始

1. 先决条件

• IDA Pro 8.3 或更高版本；建议使用 IDA 9.x
• Python 3.11 或更高版本
• uv / uvx
• 任何能够启动本地 stdio 服务的 MCP 客户端

如果尚未安装 uv，请先安装：

python -m pip install uv

激活一次 IDA 的无头 Python 环境：

# Windows — adjust the IDA version/path if needed
uv run "C:\Program Files\IDA Professional 9.3\idalib\python\py-activate-idalib.py"

# macOS — adjust the IDA version/path if needed
uv run "/Applications/IDA Professional 9.3.app/Contents/MacOS/idalib/python/py-activate-idalib.py"

2. 添加 MCP 服务

推荐的设置方式是直接运行此仓库中的最新代码：

{
  "mcpServers": {
    "ida-pro-mcp-fusion": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/rison1337/ida-pro-mcp-fusion",
        "idalib-mcp",
        "--stdio"
      ]
    }
  }
}

Claude Code：

claude mcp add ida-pro-mcp-fusion -- uvx --from git+https://github.com/rison1337/ida-pro-mcp-fusion idalib-mcp --stdio

或者从最新版本下载打包好的 MCP 套件。

3. 打开数据库

让已连接的 Agent 从以下操作开始：

idb_open(
    "C:/samples/target.exe",
    preferred_session_id="target",
    build_caches=True,
    init_hexrays=True,
)

之后，每次分析调用都会明确指定数据库：

survey_binary(database="target")
decompile("main", database="target")
xrefs_to("WinMain", database="target")
cache_callgraph_hotspots(limit=25, database="target")

架构

1. MCP 客户端通过 stdio 或 HTTP 启动 idalib-mcp。
2. 监管进程为每个二进制文件创建或接管一个工作进程，并强制执行工作进程数量上限。
3. 工具调用包含 database 会话 ID，因此请求会路由到正确的 IDB。
4. IDA 执行实时反编译和修改操作；缓存工具则从侧边 SQLite 数据库提供索引查询。
5. 工作进程在主机上始终可被发现，并在空闲 TTL 到期后自行清理。

GUI 数据库也可以参与其中。idb_open 支持四种路由模式：

模式	行为
prefer_headless	使用或创建一个 idalib 工作进程。这是默认模式。
force_headless	绝不接管正在运行的 GUI 实例。
prefer_gui	接管匹配的 GUI 实例，否则创建一个工作进程。
force_gui	接管匹配的 GUI 实例，或启动 IDA GUI。

多二进制文件工作流

打开一组小型文件，并保持每个会话都可用：

idb_batch_open(
    [
        "C:/samples/loader.exe",
        "C:/samples/payload.dll",
        "C:/samples/helper.dll",
    ],
    session_prefix="case42",
    refresh_cache=True,
    cache_include_xrefs=True,
)

对于大型语料库，构建每个缓存后立即释放其工作进程：

idb_batch_open(
    ["C:/corpus/a.exe", "C:/corpus/b.exe", "C:/corpus/c.exe"],
    close_after_cache=True,
    retry_without_auto_analysis_on_timeout=True,
)

实用的会话控制：

idb_list()
idb_close(database="case42_1_loader")

工具概览

代码库注册了 75 个面向 IDA 的分析工具，以及监管进程的多会话控制工具。客户端实际可见的确切数量会有意变化：调试器工具属于扩展功能，除非明确启用，否则会禁用危险操作；配置文件也可以只开放较小的允许列表。

类别	代表性工具
会话	idb_open、idb_batch_open、idb_list、idb_close、idb_save
概览与反编译	survey_binary、decompile、disasm、analyze_function、analyze_component
搜索与关系	find、find_bytes、search_text、xrefs_to、callees、callgraph、trace_data_flow
持久化缓存	cache_status、refresh_cache、cache_entity_query、cache_xrefs、cache_callgraph_hotspots、cache_find_regex
类型与栈	declare_type、type_inspect、set_type、infer_types、stack_frame、declare_stack
数据库编辑	rename、set_comments、define_func、define_code、patch_asm、make_data
签名	make_signature、make_signature_for_function、make_signature_for_range、find_xref_signatures
调试器扩展	dbg_start、dbg_bps、dbg_regs、dbg_stacktrace、dbg_read、dbg_write

九个专用缓存工具如下：

cache_status              refresh_cache
cache_refresh_if_stale    cache_list_funcs
cache_entity_query        cache_xrefs
cache_callgraph           cache_callgraph_hotspots
cache_find_regex

配置

工作进程池

uvx --from git+https://github.com/rison1337/ida-pro-mcp-fusion \
  idalib-mcp --stdio --max-workers 4

选项 / 变量	用途
--max-workers N	同时运行的数据库工作进程数量上限；0 表示不设上限。默认值：4。
IDA_MCP_MAX_WORKERS	工作进程数量上限的环境默认值。
IDA_MCP_OPEN_TIMEOUT	自动分析打开数据库的最长时间，单位为秒。默认值：1800；0 表示不设上限。
IDA_MCP_LOAD_TIMEOUT	仅加载打开数据库的最长时间，单位为秒。默认值：300；0 表示不设上限。

受限配置文件

仅开放经过筛选的一组工具：

idalib-mcp --stdio --profile profiles/readonly.txt

内置了两个可直接使用的配置文件：

• profiles/readonly.txt — 仅供检查，不包含修改工具
• profiles/triage.txt — 精简的初步分析工具集

管理工具仍然可用，因此仍可打开和检查会话。

HTTP 传输

idalib-mcp --host 127.0.0.1 --port 8745

IDA GUI 桥接：

ida-pro-mcp --transport http://127.0.0.1:8744/sse

如需安装 GUI 插件并通过交互方式生成客户端配置：

python -m pip install https://github.com/rison1337/ida-pro-mcp-fusion/archive/refs/heads/main.zip
ida-pro-mcp --install

安装完成后，重启 IDA 和 MCP 客户端。

安全须知

• 服务默认绑定到 loopback。请勿将其暴露给不可信网络。
• 修改类和任意 Python 工具均标记为不安全，默认不启用。
• py_eval、py_exec_file、调试器控制和补丁操作可以执行代码或永久更改 IDB。仅在客户端和输入可信时启用这些功能。
• 分析不可信二进制文件时，应将其置于与手动恶意软件分析相同的隔离边界内。

仅在工作流需要时启用不安全的工作进程工具：

idalib-mcp --stdio --unsafe

故障排除

无法识别 uvx

使用 python -m pip install uv 安装 uv，打开新的终端，然后运行 uvx --version 确认。

Python / IDA 版本不匹配

运行 Hex-Rays idapyswitch，选择 Python 3.11+ 安装，然后使用 py-activate-idalib.py 再次激活 idalib。

数据库调用提示需要 database

调用 idb_list()，并将返回的 session_id 作为 database= 传入。不能用路径和文件名代替会话 ID。

已达到工作进程上限

使用 idb_close 关闭未使用的会话，提高 --max-workers 的值，或在语料索引期间使用 close_after_cache=True。

开发

克隆代码库并运行与平台无关的测试套件：

git clone https://github.com/rison1337/ida-pro-mcp-fusion.git
cd ida-pro-mcp-fusion
python -m pip install pytest jsonschema "mcp>=1.0" "tomli-w>=1.0"
python -m pytest -q tests

在已激活的 IDA 环境中运行由 IDA 支持的测试套件：

uv run ida-mcp-test tests/typed_fixture.elf -q

新的 IDA 工具位于 src/ida_pro_mcp/ida_mcp/api_*.py 中，并通过 @tool 装饰器注册。Supervisor 和工作进程生命周期测试位于 tests/ 下。

项目身份与致谢

Fusion Edition 由 rison1337 维护。

本项目基于采用 MIT 许可证的 mrexodia/ida-pro-mcp 代码库构建。其持久化缓存和无头编排也融入了 QiuChenly/ida-pro-mcp-enhancement 和 winmin/ida-headless-mcp 中提出的理念。此处和源代码历史中均保留了致谢；Fusion 的打包、缓存工具、批处理工作流、会话生命周期和公开身份由本代码库维护。

许可证

根据 MIT License 分发。IDA Pro 和 Hex-Rays 是 Hex-Rays SA 的商标，不包含在本项目中。

---

俄语

 

一个 MCP 接入点。多个二进制文件。分析上下文得以保留。

快速开始 · 为什么选择 Fusion · 架构 · 工具 · 配置

什么是 Fusion？

IDA Pro MCP Fusion 将兼容 MCP 的 Agent 连接到 IDA Pro，并将单个连接转变为功能完备的逆向工程工作区。它将 IDA 实时分析与持久化 SQLite 索引相结合，并通过 supervisor 进程在隔离的无头工作进程中运行多个二进制文件。

你可以反编译和反汇编函数、检查交叉引用、类型和调用图、重命名符号、修补数据、创建签名，并重复使用已生成的分析结果。

重要

需要本地安装正版 IDA Pro。不支持 IDA Free。此服务不包含 IDA 或 Hex-Rays，也不会将二进制文件发送到外部服务。

Почему Fusion

	Возможность	Что это даёт
⚡	Постоянный SQLite-кэш	Функции, строки, глобальные переменные, импорты, xref и call graph доступны между запусками.
◈	Мульти-бинарный supervisor	Несколько GUI- или headless-баз управляются через одну MCP-точку.
⛓	Живущие воркеры	Следующее подключение может найти и принять уже запущенный worker для той же базы.
◎	Пакетный анализ	Открытие образцов и построение кэшей выполняется одним idb_batch_open.
⛨	Контролируемый интерфейс	Read-only-профили, лимит воркеров, тайм-ауты и opt-in для опасных инструментов.

Кэш лежит рядом с IDB в файле <database>.mcp.sqlite. Актуальность проверяется по времени изменения IDB и версии схемы, поэтому устаревшие данные не выдаются незаметно.

Быстрый старт

1. Что понадобится

• IDA Pro 8.3 или новее; рекомендуется IDA 9.x
• Python 3.11 или новее
• uv / uvx
• MCP-клиент, который умеет запускать локальный stdio-сервер

Установите uv, если его ещё нет:

python -m pip install uv

Один раз активируйте headless Python от IDA:

# Windows — при необходимости измените версию и путь к IDA
uv run "C:\Program Files\IDA Professional 9.3\idalib\python\py-activate-idalib.py"

# macOS — при необходимости измените версию и путь к IDA
uv run "/Applications/IDA Professional 9.3.app/Contents/MacOS/idalib/python/py-activate-idalib.py"

2. Добавьте MCP-сервер

Рекомендуемая конфигурация запускает код напрямую из этого репозитория:

{
  "mcpServers": {
    "ida-pro-mcp-fusion": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/rison1337/ida-pro-mcp-fusion",
        "idalib-mcp",
        "--stdio"
      ]
    }
  }
}

Для Claude Code:

claude mcp add ida-pro-mcp-fusion -- uvx --from git+https://github.com/rison1337/ida-pro-mcp-fusion idalib-mcp --stdio

Готовый MCPB-пакет доступен в последнем релизе.

3. Откройте базу

Попросите подключённого агента начать так:

idb_open(
    "C:/samples/target.exe",
    preferred_session_id="target",
    build_caches=True,
    init_hexrays=True,
)

Каждый следующий вызов анализа получает явный ID базы:

survey_binary(database="target")
decompile("main", database="target")
xrefs_to("WinMain", database="target")
cache_callgraph_hotspots(limit=25, database="target")

Архитектура

1. MCP-клиент запускает idalib-mcp через stdio или HTTP.
2. Supervisor создаёт или принимает по одному worker-процессу на каждый бинарник.
3. Каждый вызов содержит database, поэтому запрос попадает в нужную IDB-сессию.
4. IDA выполняет живой анализ и изменения, а cache-инструменты читают индекс из SQLite.
5. Воркеры остаются обнаруживаемыми на компьютере и завершаются после периода простоя.

idb_open поддерживает четыре режима:

Режим	Поведение
prefer_headless	Использовать или создать idalib-worker. Режим по умолчанию.
force_headless	Не принимать запущенный GUI-процесс.
prefer_gui	Принять подходящий GUI, а если его нет — создать worker.
force_gui	Принять GUI или запустить новый процесс IDA.

Работа с несколькими бинарниками

Открыть несколько образцов и оставить все сессии доступными:

idb_batch_open(
    [
        "C:/samples/loader.exe",
        "C:/samples/payload.dll",
        "C:/samples/helper.dll",
    ],
    session_prefix="case42",
    refresh_cache=True,
    cache_include_xrefs=True,
)

Для большого корпуса можно построить кэш и сразу освободить worker:

idb_batch_open(
    ["C:/corpus/a.exe", "C:/corpus/b.exe", "C:/corpus/c.exe"],
    close_after_cache=True,
    retry_without_auto_analysis_on_timeout=True,
)

Управление сессиями:

idb_list()
idb_close(database="case42_1_loader")

Инструменты

В кодовой базе зарегистрировано 75 инструментов анализа IDA, а supervisor добавляет управление мульти-бинарными сессиями. Видимый клиенту список намеренно меняется: debugger-инструменты являются расширением, опасные операции отключены без явного разрешения, а профиль может оставить только выбранные имена.

Область	Примеры
Сессии	idb_open, idb_batch_open, idb_list, idb_close, idb_save
Обзор и декомпиляция	survey_binary, decompile, disasm, analyze_function, analyze_component
Поиск и связи	find, find_bytes, search_text, xrefs_to, callees, callgraph, trace_data_flow
Постоянный кэш	cache_status, refresh_cache, cache_entity_query, cache_xrefs, cache_callgraph_hotspots, cache_find_regex
Типы и стек	declare_type, type_inspect, set_type, infer_types, stack_frame, declare_stack
Изменение базы	rename, set_comments, define_func, define_code, patch_asm, make_data
Сигнатуры	make_signature, make_signature_for_function, make_signature_for_range, find_xref_signatures
Debugger-расширение	dbg_start, dbg_bps, dbg_regs, dbg_stacktrace, dbg_read, dbg_write

Настройка

Пул воркеров

uvx --from git+https://github.com/rison1337/ida-pro-mcp-fusion \
  idalib-mcp --stdio --max-workers 4

Параметр / переменная	Назначение
--max-workers N	Максимум одновременно работающих баз; 0 — без лимита. По умолчанию 4.
IDA_MCP_MAX_WORKERS	Значение лимита по умолчанию из окружения.
IDA_MCP_OPEN_TIMEOUT	Максимальное время автоанализа при открытии в секундах. По умолчанию 1800.
IDA_MCP_LOAD_TIMEOUT	Максимальное время загрузки без автоанализа. По умолчанию 300.

Ограниченные профили

Оставить только выбранные инструменты:

idalib-mcp --stdio --profile profiles/readonly.txt

• profiles/readonly.txt — просмотр без инструментов изменения
• profiles/triage.txt — компактный набор для первичного анализа

HTTP

idalib-mcp --host 127.0.0.1 --port 8745

GUI-мост:

ida-pro-mcp --transport http://127.0.0.1:8744/sse

Для установки GUI-плагина:

python -m pip install https://github.com/rison1337/ida-pro-mcp-fusion/archive/refs/heads/main.zip
ida-pro-mcp --install

После установки перезапустите IDA и MCP-клиент.

Безопасность

• По умолчанию сервер слушает только loopback. Не открывайте его в недоверенную сеть.
• Изменяющие и произвольные Python-инструменты помечены как unsafe и выключены по умолчанию.
• py_eval, py_exec_file, debugger-команды и патчинг могут выполнять код или менять IDB.
• Непроверенные бинарники анализируйте в той же изоляции, что и при ручном malware analysis.

Включить unsafe-инструменты можно явно:

idalib-mcp --stdio --unsafe

Решение проблем

uvx не найден

Установите uv командой python -m pip install uv, откройте новый терминал и проверьте uvx --version.

Несовместимая версия Python или IDA

Запустите idapyswitch, выберите Python 3.11+, затем снова выполните py-activate-idalib.py.

Ошибка о том, что нужен database

Вызовите idb_list() и передайте возвращённый session_id как database=. Пути и имена файлов вместо ID сессии не принимаются.

Достигнут лимит воркеров

Закройте неиспользуемую сессию через idb_close, увеличьте --max-workers или используйте close_after_cache=True.

Разработка

git clone https://github.com/rison1337/ida-pro-mcp-fusion.git
cd ida-pro-mcp-fusion
python -m pip install pytest jsonschema "mcp>=1.0" "tomli-w>=1.0"
python -m pytest -q tests

Для тестов, которым нужна сама IDA:

uv run ida-mcp-test tests/typed_fixture.elf -q

Новые инструменты находятся в src/ida_pro_mcp/ida_mcp/api_*.py и регистрируются через @tool. Тесты supervisor и lifecycle — в tests/.

Проект и авторство

Fusion Edition поддерживается rison1337.

Проект основан на MIT-кодовой базе mrexodia/ida-pro-mcp. Постоянный кэш и headless-оркестрация также используют идеи из QiuChenly/ida-pro-mcp-enhancement и winmin/ida-headless-mcp. Атрибуция сохранена в README и истории исходников; упаковка Fusion, cache-инструменты, batch workflow и lifecycle сессий поддерживаются в этом репозитории.

Лицензия

Проект распространяется по MIT License. IDA Pro и Hex-Rays — товарные знаки Hex-Rays SA и не входят в состав проекта.