One MCP endpoint. Many binaries. Persistent analysis context.

·

·

·

·

·

What is Fusion?

IDA Pro MCP Fusion connects MCP-compatible coding agents to IDA Pro and turns a single connection into a practical reverse-engineering workspace. It combines live IDA analysis with a persistent SQLite index and a supervisor that can keep several binaries open in isolated headless workers.

Use it to decompile and disassemble functions, trace cross-references, query types, rename symbols, patch data, create signatures, inspect multiple samples, and reuse cached analysis without repeatedly walking IDA's single-threaded APIs.

> [!IMPORTANT]

> This project requires a local, licensed installation of IDA Pro. IDA Free is not supported. The server does not provide IDA, Hex-Rays, or a hosted analysis service.

Why Fusion

The cache lives beside the IDB as `.mcp.sqlite`. Freshness is checked against the IDB modification time and cache schema, so stale rows are not silently reused.

Quick start

1. Prerequisites

• IDA Pro 8.3 or newer; IDA 9.x is recommended
• Python 3.11 or newer
• `uv` / `uvx`
• Any MCP client that can launch a local stdio server

Install `uv` if it is not available:

python -m pip install uv

Activate IDA's headless Python environment once:

# 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. Add the MCP server

The recommended setup runs the latest code directly from this repository:

{
  "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

Or download the packaged MCP bundle from the latest release.

3. Open a database

Ask the connected agent to start with:

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

Every analysis call then names its database explicitly:

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

Architecture

1. Your MCP client starts `idalib-mcp` over stdio or HTTP.

2. The supervisor creates or adopts one worker per binary and enforces the worker limit.

3. Tool calls include a `database` session ID, so requests are routed to the correct IDB.

4. IDA performs live decompilation and mutation work; cache tools serve indexed queries from the sidecar SQLite database.

5. Workers remain discoverable on the host and clean themselves up after their idle TTL.

GUI databases can participate too. `idb_open` supports four routing modes:

Multi-binary workflow

Open a small collection and keep every session available:

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,
)

For a large corpus, build each cache and release its worker immediately:

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,
)

Useful session controls:

idb_list()
idb_close(database="case42_1_loader")

Tool surface

The codebase registers 75 IDA-facing analysis tools, plus the supervisor's multi-session controls. The exact number visible to a client intentionally varies: debugger tools are an extension, dangerous operations are disabled unless explicitly enabled, and a profile can expose a smaller allowlist.

The nine cache-specific tools are:

cache_status              refresh_cache
cache_refresh_if_stale    cache_list_funcs
cache_entity_query        cache_xrefs
cache_callgraph           cache_callgraph_hotspots
cache_find_regex

Configuration

Worker pool

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

Restricted profiles

Expose only a curated set of tools:

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

Two ready-to-use profiles are included:

• `profiles/readonly.txt` — inspection without mutation tools
• `profiles/triage.txt` — compact first-pass analysis surface

Management tools remain available so sessions can still be opened and inspected.

HTTP transport

idalib-mcp --host 127.0.0.1 --port 8745

IDA GUI bridge:

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

To install the GUI plugin and generate client configuration interactively:

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

Restart IDA and the MCP client after installation.

Safety notes

• The server binds to loopback by default. Do not expose it to an untrusted network.
• Mutating and arbitrary-Python tools are marked unsafe and are not enabled by default.
• `py_eval`, `py_exec_file`, debugger controls, and patching operations can execute code or permanently change an IDB. Enable them only for trusted clients and inputs.
• Analyze untrusted binaries inside the same isolation boundary you would use for manual malware analysis.

Enable unsafe worker tools only when the workflow requires them:

idalib-mcp --stdio --unsafe

Troubleshooting

uvx is not recognized

Install `uv` with `python -m pip install uv`, open a new terminal, and confirm with `uvx --version`.

Python / IDA version mismatch

Run Hex-Rays `idapyswitch`, select a Python 3.11+ installation, then activate idalib again with `py-activate-idalib.py`.

A database call says that database is required

Call `idb_list()` and pass the returned `session_id` as `database=`. Paths and filenames are not accepted in place of a session ID.

The worker limit has been reached

Close an unused session with `idb_close`, raise `--max-workers`, or use `close_after_cache=True` for corpus indexing.

Development

Clone the repository and run the platform-independent test suite:

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

Run the IDA-backed suite in an activated IDA environment:

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

New IDA tools live in `src/ida_pro_mcp/ida_mcp/api_*.py` and register through the `@tool` decorator. Supervisor and worker lifecycle tests live under `tests/`.

Project identity and credits

Fusion Edition is maintained by rison1337.

The project builds on the MIT-licensed `mrexodia/ida-pro-mcp` codebase. Its persistent cache and headless orchestration also incorporate ideas developed in `QiuChenly/ida-pro-mcp-enhancement` and `winmin/ida-headless-mcp`. Attribution is retained here and in the source history; Fusion's packaging, cache tooling, batch workflow, session lifecycle, and public identity are maintained in this repository.

License

Distributed under the MIT License. IDA Pro and Hex-Rays are trademarks of Hex-Rays SA and are not included with this project.

Русский

 

Одна MCP-точка. Много бинарников. Контекст анализа сохраняется.

·

·

·

·

Что такое Fusion?

IDA Pro MCP Fusion подключает MCP-совместимых агентов к IDA Pro и превращает одно соединение в полноценное рабочее место для реверсинга. Живой анализ IDA объединён с постоянным SQLite-индексом и supervisor-процессом, который может держать несколько бинарников в изолированных headless-воркерах.

Можно декомпилировать и дизассемблировать функции, исследовать перекрёстные ссылки, типы и граф вызовов, переименовывать символы, патчить данные, создавать сигнатуры и повторно использовать уже построенный анализ.

> [!IMPORTANT]

> Нужна локальная лицензированная установка IDA Pro. IDA Free не поддерживается. Сервер не содержит IDA, Hex-Rays и не отправляет бинарники во внешний сервис.

Почему Fusion

Кэш лежит рядом с IDB в файле `.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` поддерживает четыре режима:

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

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

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-инструменты являются расширением, опасные операции отключены без явного разрешения, а профиль может оставить только выбранные имена.

Настройка

Пул воркеров

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

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

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

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 и не входят в состав проекта.