Skip to main content
Glama
ida-fusion-mcp

ida-fusion-mcp

by andsopwn

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.

License Python IDA Pro MCP

ida-fusion-mcp architecture

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 Pro MCP

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 control

dbg_start, dbg_status, dbg_exit, dbg_continue, dbg_run_to, dbg_step_into, dbg_step_over

Breakpoints

dbg_bps, dbg_add_bp, dbg_delete_bp, dbg_toggle_bp, dbg_set_bp_condition

Registers and stack

dbg_regs_all, dbg_regs, dbg_regs_remote, dbg_gpregs, dbg_gpregs_remote, dbg_regs_named, dbg_regs_named_remote, dbg_stacktrace

Debugger memory

dbg_read, dbg_write

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

Mode

IDA edition/version

Python

Extra package

GUI plugin

IDA Pro/Home 8.3+

IDA's matching Python, server on 3.11+

none

Managed headless

IDA Pro 9.x with libidalib

server/worker on 3.11+

ida-fusion-mcp[idalib]

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:

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.

Available Tools

66 tools
analyze_componentA

Analyze related functions as a group: per-function compact summaries, internal call graph (edges only between supplied functions), shared globals, interface vs internal classification, and strings used by multiple members.

Inputs: addrs (required), instance_id (required). Returns: functions, internal_call_graph, shared_globals, interface_functions, +3 more

analyze_functionA

Compact single-function analysis: pseudocode (capped at 100 lines), top strings, top non-trivial constants, callers, callees, xrefs, comments, and basic block summary. Use this for "tell me everything about function X" in one call instead of chaining decompile + callees + xrefs_to separately.

Inputs: addr (required), instance_id (required), include_asm. Returns: addr, name, prototype, size, +11 more

append_commentsA

Append comments at addresses, deduping exact text by default. Unlike set_comments (which overwrites), this preserves existing annotations — use it for incremental commentary. scope='auto' (default) writes a function comment when addr is a function start, otherwise a line comment; force with scope='func' or 'line'. dedupe=True skips writes when the exact stripped text already appears on its own line.

Inputs: items (required), instance_id (required). Returns: result

basic_blocksB

Get control flow graph basic blocks for functions

Inputs: addrs (required), instance_id (required), max_blocks, offset. Returns: result

calleesC

Get functions called by the specified functions

Inputs: addrs (required), instance_id (required), limit. Returns: result

callgraphB

Build call graph starting from root functions

Inputs: roots (required), instance_id (required), max_depth, max_nodes, +2 more. Returns: result

compare_binariesA

Compare two IDA instances by diffing their binary metadata, entrypoints, and segments. Takes two instance_id values and returns what is common vs unique to each.

Inputs: instance_id_a (required), instance_id_b (required). Returns: object

dbg_gpregsB

Get general-purpose registers for the current thread.

Inputs: instance_id (required). Returns: object

dbg_gpregs_remoteB

Get general-purpose registers for specified thread IDs.

Inputs: tids (required), instance_id (required). Returns: object

dbg_regs_namedB

Get selected registers for the current thread.

Inputs: register_names (required), instance_id (required). Returns: object

dbg_regs_named_remoteB

Get selected registers for a specific thread ID.

Inputs: thread_id (required), register_names (required), instance_id (required). Returns: object

dbg_set_bp_conditionB

Set or clear breakpoint conditions in batch.

Inputs: items (required), instance_id (required). Returns: object

dbg_statusB

Return debugger lifecycle state and current IP if suspended.

Inputs: instance_id (required). Returns: object

declare_stackC

Create stack vars

Inputs: items (required), instance_id (required). Returns: object

declare_typeD

Declare types

Inputs: decls (required), instance_id (required). Returns: result

decompileB

Decompile function to pseudocode

Inputs: addr (required), instance_id (required). Returns: object

decompile_to_fileA

Decompile functions and save results directly to files on disk. IMPORTANT: Each function requires a separate IDA decompile call. For large binaries, check function count with list_funcs first before using 'all'. Hundreds of functions can take minutes; thousands can take much longer.

Inputs: output_dir (required), instance_id (required), addrs, all, +1 more. Returns: object

define_codeA

Convert raw bytes to a code instruction at each given address. Returns {addr, ea, length} on success (length is the instruction byte length) or {addr, ea, error} if create_insn failed. Use this when IDA classified an instruction as data or failed to decode.

Inputs: items (required), instance_id (required). Returns: result

define_funcA

Define a function at each given address. IDA infers bounds unless an explicit end address is provided. Returns {addr, start, end} on success or {addr, start, error} if the function already exists or add_func fails. Use this when IDA auto-analysis missed a function entry point.

Inputs: items (required), instance_id (required). Returns: result

delete_stackC

Delete stack vars

Inputs: items (required), instance_id (required). Returns: object

diff_before_afterA

Apply a rename/type/comment action and return the before/after decompilation side by side. Actions: 'rename_func' ({name}), 'set_type' ({type}), 'set_comment' ({comment}). Useful to verify a rename or type change actually improved readability. Returns {before, after, action_applied, changes_detected}.

Inputs: addr (required), action (required), action_args (required), instance_id (required). Returns: before, after, action_applied, changes_detected, +1 more

disasmA

Disassemble function to assembly instructions

Inputs: addr (required), instance_id (required), max_instructions, offset, +1 more. Returns: object

entity_queryB

Query IDB entities with filtering, projection, and pagination.

Inputs: queries (required), instance_id (required). Returns: object

export_funcsC

Export function data in various formats

Inputs: addrs (required), instance_id (required), format. Returns: object

findB

Search for patterns in the binary (strings, immediate values, or references)

Inputs: type (required), targets (required), instance_id (required), limit, +1 more. Returns: result

find_bytesB

Search for byte patterns in the binary (supports wildcards with ??)

Inputs: patterns (required), instance_id (required), limit, offset. Returns: result

find_regexB

Search strings with case-insensitive regex patterns

Inputs: pattern (required), instance_id (required), limit, offset. Returns: object

find_xref_signaturesB

Find signatures for code locations that reference an address.

Inputs: addrs (required), instance_id (required), format, top, +1 more. Returns: object

get_bytesB

Read bytes from memory addresses

Inputs: regions (required), instance_id (required). Returns: result

get_cached_outputA

Retrieve cached output from a previous tool call that was truncated. Use this to get additional chunks of large responses.

Inputs: cache_id (required), offset, size. Returns: object

get_global_valueA

Read global variable values by address or name (auto-detects hex addresses vs names)

Inputs: queries (required), instance_id (required). Returns: result

get_intB

Read integer values from memory addresses

Inputs: queries (required), instance_id (required). Returns: result

get_stringB

Read strings from memory addresses

Inputs: addrs (required), instance_id (required). Returns: result

importsC

List imports

Inputs: offset (required), count (required), instance_id (required). Returns: object

infer_typesC

Infer types

Inputs: addrs (required), instance_id (required). Returns: result

int_convertC

Convert numbers to different formats

Inputs: inputs (required), instance_id (required). Returns: result

list_cached_outputsA

List all cached truncated outputs with cache_id, age, size, and tool name. Use this to find cache IDs for get_cached_output.

Inputs: no named parameters. Returns: object

list_funcsA

List functions WARNING: IDA executes on a single main thread. Long-running operations will block ALL subsequent requests and make IDA unresponsive. For large binaries (100K+ functions), use count/offset pagination. Avoid count=0 (all) with glob filters on large binaries.

Inputs: queries (required), instance_id (required). Returns: result

list_globalsD

List globals

Inputs: queries (required), instance_id (required). Returns: result

list_instancesA

List all registered IDA Pro instances with their metadata.

Inputs: no named parameters. Returns: count, instances

lookup_funcsB

Get functions by address or name (auto-detects)

Inputs: queries (required), instance_id (required). Returns: result

make_signatureB

Create unique byte signatures for addresses.

Inputs: addrs (required), instance_id (required), format, wildcard_operands, +1 more. Returns: object

make_signature_for_functionB

Create unique byte signatures for function entry points.

Inputs: addrs (required), instance_id (required), format, wildcard_operands, +1 more. Returns: object

make_signature_for_rangeA

Create a byte signature for an explicit address range.

Inputs: start (required), end (required), instance_id (required), format, +1 more. Returns: object

patchB

Patch bytes at memory addresses with hex data

Inputs: patches (required), instance_id (required). Returns: result

patch_asmC

Patch assembly instructions at addresses

Inputs: items (required), instance_id (required). Returns: result

put_intB

Write integer values to memory addresses

Inputs: items (required), instance_id (required). Returns: result

py_evalA

Execute Python code in IDA context. Returns dict with result/stdout/stderr. Has access to all IDA API modules. Supports Jupyter-style evaluation. WARNING: IDA executes on a single main thread. Long-running operations will block ALL subsequent requests and make IDA unresponsive. Do NOT iterate all functions, bulk decompile, or run heavy loops. Use decompile_to_file for batch decompilation instead.

Inputs: code (required), instance_id (required). Returns: object

py_exec_fileC

Execute a Python script file in IDA context.

Inputs: file_path (required), instance_id (required). Returns: object

read_structA

Reads struct type definition and parses actual memory values at the given address as instances of that struct type.

If struct name is not provided, attempts to auto-detect from address. Auto-detection only works if IDA already has type information applied at that address

Returns struct layout with actual memory values for each field.

Inputs: queries (required), instance_id (required). Returns: result

refresh_cachesA

Force-refresh all caches (strings, functions, globals). Call this after bulk modifications to ensure list_funcs/list_globals return fresh data.

Inputs: instance_id (required). Returns: strings, functions, globals, time_ms

refresh_toolsC

Re-discover tools from IDA Pro instances.

Inputs: no named parameters. Returns: object

renameC

Unified rename operation for functions, globals, locals, and stack variables

Inputs: batch (required), instance_id (required). Returns: object

search_structsD

Search structs

Inputs: filter (required), instance_id (required). Returns: result

search_textC

Search rendered listing text using IDA native text search.

Inputs: pattern (required), instance_id (required), limit, start, +4 more. Returns: object

set_commentsC

Set comments at addresses (both disassembly and decompiler views)

Inputs: items (required), instance_id (required). Returns: object

set_typeB

Apply types (function/global/local/stack)

Inputs: edits (required), instance_id (required). Returns: result

stack_frameC

Get stack vars

Inputs: addrs (required), instance_id (required). Returns: result

survey_binaryA

Get a compact overview of the binary in one call. Returns file metadata, segment layout, entry points, statistics, top 15 strings and functions ranked by xref count (functions include classification: thunk/wrapper/leaf/dispatcher/ complex), imports by category, and call graph summary. Use this as your FIRST tool call when starting analysis. Do not call list_funcs, imports, or find_regex separately for triage — this returns all of that. Use detail_level='minimal' for binaries with >10k functions.

Inputs: instance_id (required), detail_level. Returns: metadata, statistics, segments, entrypoints, +5 more

trace_data_flowA

Follow cross-references from or to an address, automatically traversing multiple hops. 'forward' follows xrefs-from, 'backward' follows xrefs-to. Returns nodes (with function name, instruction, code/data classification) and edges. Do not use for call graph traversal — use callgraph for that.

Inputs: addr (required), instance_id (required), direction, max_depth. Returns: start, direction, depth_reached, nodes, +2 more

type_apply_batchC

Apply multiple type edits and return aggregate status.

Inputs: batch (required), instance_id (required). Returns: object

type_inspectC

Inspect named types with size, declaration, and optional member layout.

Inputs: queries (required), instance_id (required). Returns: object

type_queryC

Query local types with structured filters and pagination.

Inputs: queries (required), instance_id (required). Returns: object

undefineA

Undefine item(s) at each address, converting them back to raw bytes. Size is determined from end (exclusive) or size; defaults to 1 byte. Uses ida_bytes.DELIT_EXPAND so adjacent items spanning into the range are fully removed. Returns {addr, start, size} on success.

Inputs: items (required), instance_id (required). Returns: result

xrefs_toC

Get cross-references to specified addresses

Inputs: addrs (required), instance_id (required), limit. Returns: result

xrefs_to_fieldC

Get cross-references to structure fields

Inputs: queries (required), instance_id (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.6/5.0

    Scored across 66 tools

    Disambiguation2/5

    Many tools overlap in purpose, e.g., multiple ways to read memory (get_bytes, get_global_value, get_int, get_string, read_struct), multiple search tools (find, find_bytes, find_regex, search_text), and multiple debugging register tools. Agents would struggle to pick the right one.

    Naming Consistency2/5

    Naming conventions are mixed: some use verb_noun (list_funcs, find_bytes), some are verb-only (callees, imports), some use descriptive phrases (diff_before_after, survey_binary), and debug tools use a dbg_ prefix. No consistent pattern exists.

    Tool Count2/5

    66 tools is excessive for a binary analysis server. Many tools could be consolidated (e.g., memory-reading tools, debug register tools). The high count likely leads to agent confusion and inefficiency.

    Completeness4/5

    The tool surface covers most aspects of binary analysis: disassembly, decompilation, patching, debugging, type management, cross-references, and searching. Minor gaps exist (e.g., no standalone segment listing, no type renaming), but overall it is fairly complete.

    Maintenance

    ActivityInactive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      B
      maintenance
      Enables large language models to read and write IDA Pro databases through structured tool calls for reverse engineering, binary analysis, and hook development. Provides broker-based routing, SQLite-backed static caching, multi-instance analysis, and both cached and live IDA API queries.
      66
      5
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to remotely control IDA Pro for reverse engineering and binary analysis, including executing Python scripts, retrieving strings/imports/exports/functions, searching values/text/bytes, and obtaining disassembly.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to interact with IDA Pro for reverse engineering and binary analysis, including running Python scripts, retrieving strings/imports/exports/functions, searching immediates/text/bytes, and getting disassembly.
      -