ida-fusion-mcp

ida-fusion-mcp is a fork and continuation of MeroZemory/ida-multi-mcp. It keeps the original multi-instance IDA routing model, renames the public project, and adds a larger tool surface ported from ida-pro-mcp.

The goal is straightforward: one MCP endpoint for reverse-engineering work that spans more than one IDA database. Your AI client keeps one stable server config, and each tool call is routed to the correct IDA Pro GUI instance or headless idalib worker by instance_id.

v0.1.1 stabilization candidate: fixes synchronization, installer safety, debugger routing/schema parity, macOS detection, and selected correctness issues. It is a local candidate only; no tag, package, or public release has been published.

The project combines three things that are usually separate:

• multi-binary routing for loaders, payloads, plugins, services, and shared libraries;

• a broad IDA tool surface adapted from ida-pro-mcp;

• headless IDA Pro sessions for background analysis without opening another GUI window.

What Problem It Solves

Most IDA MCP setups assume a single active database. That is awkward once an investigation needs context from several files at once: a dropper and payload, a patched and unpatched build, a client and server pair, or a main executable plus libraries.

ida-fusion-mcp makes the target explicit. The AI client first asks for registered instances, receives short IDs such as k7m2 or px3a, and includes one of those IDs in every IDA tool call. That small constraint prevents a common failure mode: the model decompiles, renames, patches, or debugs the wrong database because two IDA windows are open.

Related MCP server: IDA Auto MCP

Core Ideas

Tool Surface

The IDA-side tools cover the normal reverse-engineering loop: discovery, navigation, decompilation, xrefs, memory reads, patching, type work, comments, stack variables, debugger access, and binary triage.

The recent port from ida-pro-mcp adds these higher-level capabilities:

Router-level tools add multi-instance operations:

Comparison

Quick Start

Install the package, install the IDA loader, then open binaries in IDA.

python -m pip install git+https://github.com/andsopwn/ida-fusion-mcp.git
ida-fusion-mcp --install
ida-fusion-mcp --list

Example client prompt:

Call list_instances, identify the two open binaries, decompile their entry points, and compare the initialization paths.

The legacy ida-multi-mcp console command is still provided as an alias. New configuration uses ida-fusion-mcp.

Installation Details

Requirements

Post-change v0.1.1 GUI routing and managed idalib are verified with IDA Pro 9.3 on macOS arm64, including a real GUI restart and managed-session lifecycle.

macOS

IDA often uses a different Python build than your shell. Check IDA's Python first:

import sys
print(sys.version)

Then install with the matching Python version:

pipx install git+https://github.com/andsopwn/ida-fusion-mcp.git
python3.11 -m pip install --user git+https://github.com/andsopwn/ida-fusion-mcp.git
ida-fusion-mcp --install

For Claude Code, a direct CLI registration is usually clearer than a module command:

claude mcp add ida-fusion-mcp -s user -- ida-fusion-mcp

For managed headless sessions, install the optional idapro dependency into a Python 3.11 environment. Persist that exact worker interpreter in the MCP client registration; running the server once with the flag does not update the client's saved configuration. Use this registration instead of the GUI-only Claude Code command above:

python3.11 -m pip install \
  "ida-fusion-mcp[idalib] @ git+https://github.com/andsopwn/ida-fusion-mcp.git"
claude mcp add ida-fusion-mcp -s user -- \
  ida-fusion-mcp --idalib-python /absolute/path/to/idalib-python

For JSON-based clients, store the same argument in the server entry:

{
  "command": "/absolute/path/to/server-python",
  "args": ["-m", "ida_fusion_mcp", "--idalib-python", "/absolute/path/to/idalib-python"]
}

GUI mode does not require idapro. Headless mode requires IDA Pro 9.x with libidalib and an interpreter where import idapro is discoverable.

Windows

py -3.11 -m pip install git+https://github.com/andsopwn/ida-fusion-mcp.git
ida-fusion-mcp --install

If IDA uses a different Python version, replace 3.11 with IDA's version. For a custom IDA directory:

ida-fusion-mcp --install --ida-dir "C:\Program Files\IDA Professional 9.3"

Linux

python3 -m pip install --user git+https://github.com/andsopwn/ida-fusion-mcp.git
ida-fusion-mcp --install

Manual MCP Config

ida-fusion-mcp --install writes client configs automatically when it recognizes the client. To inspect the raw MCP config:

ida-fusion-mcp --config

Typical output:

{
  "mcpServers": {
    "ida-fusion-mcp": {
      "command": "/path/to/python3",
      "args": ["-m", "ida_fusion_mcp"]
    }
  }
}

Using It

Open one or more binaries in IDA Pro. The loader installed by --install starts an IDA-local HTTP server and registers the database in ~/.ida-mcp/instances.json.

Check what is live:

ida-fusion-mcp --list

Then use the displayed instance_id in prompts or tool arguments:

Use instance k7m2. Find functions referencing the string "license", decompile the callers, and summarize the validation path.

For two binaries:

Use k7m2 as the old build and px3a as the patched build. Compare the functions around the entry point and report changed calls.

For headless work:

Open /samples/payload.bin with idalib_open, wait for analysis, then run survey_binary on the returned instance.

Architecture

AI client
  |
  | MCP stdio
  v
ida-fusion-mcp router
  |-- local registry and schema cache
  |-- output cache for large responses
  |-- idalib worker manager
  |
  | HTTP JSON-RPC on loopback
  v
IDA GUI #1    IDA GUI #2    idalib worker #1

The router does not own IDA analysis state. It validates the requested instance_id, forwards the call to the matching backend, normalizes large outputs, and returns the MCP response to the client.

Operational Notes

• The installed IDA loader is named ida_fusion_mcp_loader.py so it does not shadow the ida_fusion_mcp package when IDA imports plugins by filename.

• The implementation module remains ida_fusion_mcp.

• The registry lives under ~/.ida-mcp/ by default.

• GUI instances send heartbeats; stale entries are cleaned up.

• If an IDA window opens a different input file, the old instance expires and a new ID is registered.

• The stdio router advertises debugger tools normally and internally enables the IDA backend's dbg extension for discovery and invocation. Clients pass only instance_id; unsafe-tool configuration and debugger-state checks stay enforced by the backend.

• py_eval and py_exec_file are unsafe, in-process code-execution tools. Their reduced builtins/import surface is defense in depth, not containment; disable them in the IDA MCP tool configuration unless the workflow requires them. Managed idalib workers omit @unsafe tools unless opened with unsafe=true; the GUI plugin retains its existing enabled-tool defaults for compatibility.

Troubleshooting

IDA does not show the plugin

Check that the loader exists:

ls ~/.idapro/plugins/ida_fusion_mcp_loader.py

On Windows:

Get-Item "$env:APPDATA\Hex-Rays\IDA Pro\plugins\ida_fusion_mcp_loader.py"

If IDA reports No module named 'ida_fusion_mcp', install the package with the Python version used by IDA. If IDA itself is using Python older than 3.11, switch IDA to a supported Python build with idapyswitch.

The MCP client starts the wrong Python

Run:

ida-fusion-mcp --config

If the generated command points to an unexpected interpreter, configure the client to call the ida-fusion-mcp CLI directly.

No instances are listed

Start IDA with a binary loaded, then run:

ida-fusion-mcp --list

If the list is still empty, check the IDA output window for [ida-fusion-mcp] messages.

Development

git clone https://github.com/andsopwn/ida-fusion-mcp.git
cd ida-fusion-mcp
python -m venv .venv
. .venv/bin/activate
python -m pip install -e .
python -m compileall -q src
python -m ida_fusion_mcp --config

The public package exposes both commands:

ida-fusion-mcp --config
ida-multi-mcp --config   # compatibility alias

Lineage And License

ida-fusion-mcp is MIT licensed. See LICENSE.

This repository is based on and extends MIT-licensed work from:

• ida-multi-mcp, the original multi-instance IDA MCP router.

• ida-pro-mcp, copyright (c) 2025 Duncan Ogilvie.

• ida-sigmaker, copyright (c) 2024 Mahmoud Abdelkader.

Those attributions are intentional: this project is ida-multi-mcp plus additional ported functionality, packaging the useful IDA tool surface into a router-oriented workflow for multi-binary analysis.