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.

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.

Core Ideas

Idea	Practical effect
One MCP server	Configure Claude Code, Cursor, Codex, VS Code, or another MCP client once.
Many IDA backends	GUI IDA instances and headless idalib workers register into the same local registry.
Required instance_id	Tool calls are deliberately scoped to one database.
Static + dynamic schemas	Tools are visible before IDA is open, then refreshed from live IDA instances.
Local-only transport	IDA listens on loopback HTTP JSON-RPC; the MCP server talks stdio to the client.
Compatibility aliases	The public name is ida-fusion-mcp; the Python implementation package remains ida_fusion_mcp to avoid breaking existing imports.

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:

Category	Tools
Signature generation	make_signature, make_signature_for_function, make_signature_for_range, find_xref_signatures
Type catalog	type_query, type_inspect, type_apply_batch
Unified search	entity_query, search_text
IDAPython file execution	py_exec_file
Debugger helpers	dbg_status, dbg_set_bp_condition, dbg_gpregs, dbg_gpregs_remote, dbg_regs_named, dbg_regs_named_remote

Router-level tools add multi-instance operations:

Tool	Purpose
list_instances	Show every registered GUI or headless IDA backend.
refresh_tools	Refresh schemas from currently connected IDA instances.
compare_binaries	Compare metadata and segments from two registered instances.
decompile_to_file	Save decompiler output to disk without stuffing huge output into chat.
get_cached_output	Retrieve follow-up chunks from truncated large responses.
idalib_open / idalib_close / idalib_list / idalib_status	Manage headless IDA Pro sessions.

Comparison

Capability	ida-fusion-mcp	ida-pro-mcp	Typical single-instance MCP
Multiple GUI IDA windows	First-class workflow	Not the main focus	Usually awkward
Per-call target selection	Required instance_id	Context/session dependent	Often implicit
Headless IDA Pro	Managed idalib workers in the same registry	idalib-mcp supervisor model	Often absent
Signature/type/search tools	Included from the port	Included upstream	Varies
Cross-binary helpers	Included at router level	Not the focus	Usually absent
Best fit	Multi-file investigations and agent workflows	Upstream single-database IDA tooling	One binary at a time

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

• Python 3.11 or newer for the MCP server.
• IDA Pro 8.3 or newer.
• IDA's embedded Python must also be able to import the installed package.
• idalib features require IDA Pro; IDA Home/Free do not provide headless idalib.

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

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.py.
• 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.
• Debugger extension tools are available from the IDA-side MCP server with the debugger extension enabled; router schemas expose the callable tool names to clients.

Troubleshooting

IDA does not show the plugin

Check that the loader exists:

ls ~/.idapro/plugins/ida_fusion_mcp.py

On Windows:

Get-Item "$env:APPDATA\Hex-Rays\IDA Pro\plugins\ida_fusion_mcp.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 ".[dev]"
python -m pytest -q

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.