IDA Pro MCP Fusion

One MCP endpoint. Many binaries. Persistent analysis context.

Quick start · Why Fusion · Architecture · Tools · Configuration · Development

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