ida-pro-mcp-fusion

 

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

	Capability	What it changes
⚡	Persistent SQLite cache	Functions, strings, globals, imports, xrefs, and call-graph edges remain queryable across repeated investigations.
◈	Multi-binary supervisor	Open, address, and close several GUI or headless databases through one MCP endpoint.
⛓	Persistent workers	A later supervisor can discover and adopt an existing worker for the same database.
◎	Batch-first workflow	Warm analysis and build caches for a collection of samples with one idb_batch_open call.
⛨	Controlled surface	Read-only profiles, opt-in unsafe tools, worker limits, timeouts, and idle cleanup keep automation bounded.

The cache lives beside the IDB as <database>.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:

Mode	Behaviour
prefer_headless	Use or create an idalib worker. This is the default.
force_headless	Never adopt a running GUI instance.
prefer_gui	Adopt a matching GUI instance, otherwise create a worker.
force_gui	Adopt a matching GUI instance or launch IDA GUI.

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.

Area	Representative tools
Sessions	idb_open, idb_batch_open, idb_list, idb_close, idb_save
Survey & decompilation	survey_binary, decompile, disasm, analyze_function, analyze_component
Search & relationships	find, find_bytes, search_text, xrefs_to, callees, callgraph, trace_data_flow
Persistent cache	cache_status, refresh_cache, cache_entity_query, cache_xrefs, cache_callgraph_hotspots, cache_find_regex
Types & stack	declare_type, type_inspect, set_type, infer_types, stack_frame, declare_stack
Database editing	rename, set_comments, define_func, define_code, patch_asm, make_data
Signatures	make_signature, make_signature_for_function, make_signature_for_range, find_xref_signatures
Debugger extension	dbg_start, dbg_bps, dbg_regs, dbg_stacktrace, dbg_read, dbg_write

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

Option / variable	Purpose
--max-workers N	Maximum simultaneous database workers; 0 means unlimited. Default: 4.
IDA_MCP_MAX_WORKERS	Environment default for the worker limit.
IDA_MCP_OPEN_TIMEOUT	Maximum auto-analysis open time in seconds. Default: 1800; 0 disables the limit.
IDA_MCP_LOAD_TIMEOUT	Maximum load-only open time in seconds. Default: 300; 0 disables the limit.

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

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

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

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

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.

---

Русский

Что такое Fusion?

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

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

[!IMPORTANT] Нужна локальная лицензированная установка 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

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

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

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

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