ida-multi-mcp

Multi-instance IDA Pro MCP server for simultaneous reverse engineering of multiple binaries through a single MCP endpoint. Supports both GUI instances and headless analysis via idalib (IDA Pro only).

✨ What’s New

• Function similarity search (BCSD) — locate the same or similar function within a binary or across instances (patch diffing, library-function ID, variant hunting). Name-independent signals that survive stripping — instruction-shingle MinHash + imported-API / string / constant anchors + CFG structure/shape — with an optional on-demand local neural recall (jTrans embeddings) for cross-compiler twins. All local, no cloud. → details

Why ida-multi-mcp?

Analyze multiple binaries in parallel — dropper, payload, C2 — through a single MCP connection. Each IDA Pro instance auto-registers on startup; your LLM client sees every instance without touching its config.

Quick Start

Just ask your AI agent to install it. Copy-paste one of these prompts — it handles the Python version matching, IDA plugin placement, and MCP client registration for you.

Claude Code / AmpCode:

Install and configure ida-multi-mcp by following the instructions here: https://raw.githubusercontent.com/MeroZemory/ida-multi-mcp/main/docs/installation.md

Cursor:

@Web fetch https://raw.githubusercontent.com/MeroZemory/ida-multi-mcp/main/docs/installation.md and follow the installation steps.

Once installed, open your binaries in IDA Pro (instances auto-register) and ask your LLM:

“Decompile main in malware.exe (k7m2) and compare it with the entry point in dropper.dll (px3a)”

Prefer to install by hand? See Manual Installation below.

How It Works

MCP Client (Claude, Cursor, etc.)
    │  stdio (MCP Protocol)
    ▼
┌──────────────────────────────────────┐
│  ida-multi-mcp Server (Router)       │
│  - Dynamic tool discovery            │
│  - instance_id routing               │
│  - Management + idalib lifecycle     │
└───┬──────┬──────┬──────┬─────────────┘
    │      │      │      │  HTTP JSON-RPC
    ▼      ▼      ▼      ▼
  IDA #1  IDA #2  IDA #3  idalib #1
  (GUI)   (GUI)   (GUI)   (headless)

Features

• Zero-configuration instance discovery — Each IDA Pro instance auto-registers on startup
• Headless analysis (IDA Pro) — Open binaries without GUI via idalib_open — each session runs as an isolated subprocess
• Port-collision free — Uses OS auto-assigned ports (port 0)
• Dynamic tool discovery — All 80+ IDA tools available automatically
• 1-call binary triage — survey_binary returns metadata, segments, top strings/functions, imports, and call graph in one call
• Cross-binary analysis — Target specific instances via instance_id parameter
• Function-similarity search — similar_functions / compare_functions rank BCSD matches (instruction-shingle MinHash + API/string/constant anchors + CFG/shape) within a binary or across instances. Optional on-demand neural recall (jTrans embeddings) recovers anchor-less cross-compiler twins that lexical/structural signals miss — enable with pip install ida-multi-mcp[neural] + IDA_MCP_SIM_NEURAL=1 (model auto-downloads to ~/.ida-mcp/models/)
• Smart instance tracking — 4-character IDs (k7m2, px3a, etc.) with automatic binary-change detection
• IDA 8.3–9.3 compatible — Built-in version compatibility shims (compat.py)
• File-based registry — Tracks all active instances (GUI and headless)
• Graceful fallback — Handles binary changes, stale instances, and crashes

Requirements

• Python 3.11 or later
• IDA Pro 8.3+ (9.0 recommended)

Manual Installation

Already used the AI-agent prompt in Quick Start? You can skip this section.

Pick your platform:

AI-agent reference

The canonical installation guide an AI agent should follow is at docs/installation.md. It covers platform-specific package installation, IDA Python version matching, plugin setup via ida-multi-mcp --install, and verification.

Supported MCP Clients

Works with any MCP-compatible client. ida-multi-mcp --install auto-configures all detected clients (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Zed, and 20+ more).

Manual MCP Client Configuration

For clients not auto-detected or to view the raw configuration JSON:

ida-multi-mcp --config

Uninstallation

After uninstalling, fully restart IDA Pro and your MCP client(s) so the removed configuration is picked up.

Usage

Opening Multiple Binaries (GUI Mode)

1. Open IDA Pro and load your first binary (e.g., malware.exe)

   • Plugin auto-loads (PLUGIN_FIX flag)
   • Instance auto-registers with 4-char ID (e.g., k7m2)

2. Open another IDA Pro instance with a second binary (e.g., dropper.dll)

   • Another instance auto-registers (e.g., px3a)

3. Repeat for more binaries

Headless Analysis (IDA Pro Only)

Requires IDA Pro license. IDA Home/Free do not include idalib.

Open binaries without a GUI — each session runs as an isolated subprocess:

> Use idalib_open to analyze /path/to/malware.exe headlessly

The LLM calls idalib_open(input_path="/path/to/malware.exe"), which spawns a headless idalib process, waits for auto-analysis, and returns an instance_id. From that point, all 80+ IDA tools work exactly as with a GUI instance.

To specify a custom Python with idapro installed, start the server with:

ida-multi-mcp --idalib-python /path/to/python3.11

Viewing Registered Instances

ida-multi-mcp --list

Output:

Registered IDA instances (3):

  k7m2
    Binary: malware.exe
    Path: C:/samples/malware.exe
    Arch: x86_64
    Port: 49152
    PID: 12345

  px3a
    Binary: dropper.dll
    Path: C:/samples/dropper.dll
    Arch: x86_64
    Port: 49153
    PID: 12346

  9bf1
    Binary: payload.exe
    Path: C:/samples/payload.exe
    Arch: x86
    Port: 49154
    PID: 12347

Using in Your LLM

Once connected, all 80+ IDA tools are available. All IDA tool calls require the instance_id parameter to avoid cross-agent contention.

Analyzing a single instance:

Decompile the main function in malware.exe (k7m2)

Cross-binary analysis:

Decompile main in malware.exe (k7m2) and compare it with the entry point in dropper.dll (px3a)

Function similarity (patch diff, library ID, variant hunting):

Index malware.exe (k7m2) and dropper.dll (px3a), then find the function in dropper.dll most similar to sub_140001000 in malware.exe

Management Tools

The server provides built-in management tools:

list_instances()

Lists all registered instances with metadata (binary name, path, architecture, port, type: gui or idalib).

refresh_tools()

Re-discovers tools from IDA instances. Use this if you update the IDA plugin.

get_cached_output(cache_id, offset, size)

Retrieve cached output from a previous tool call that was truncated.

decompile_to_file(…)

Decompile functions and save results directly to files on disk. Requires instance_id.

idalib_open(input_path, timeout, unsafe) (IDA Pro only)

Open a binary in a new headless idalib session. Spawns a subprocess, waits for auto-analysis, registers in the shared registry.

idalib_close(instance_id) (IDA Pro only)

Terminate a headless idalib session and remove it from the registry.

idalib_list() (IDA Pro only)

List all managed headless idalib sessions.

idalib_status(instance_id) (IDA Pro only)

Health/readiness check for a specific idalib session.

Function Similarity (BCSD)

Local, cross-instance binary code similarity — no cloud, no external service. Signals are name-independent (survive stripping): instruction-shingle MinHash, IDF-weighted imported-API / string / constant anchors, and CFG structure/shape, plus symbol-gated pseudocode tokens. An optional [neural] extra adds on-demand jTrans embeddings for anchor-less cross-compiler matches.

• index_functions(instance_id, rebuild=False) — build/refresh the searchable index for a binary (content-hash keyed, persisted under ~/.ida-mcp/index/, incremental, backgroundable).
• index_status(instance_id) — index readiness, function count, staleness, and background progress.
• similar_functions(instance_id, func, top_k=20, scope="binary"|"instances"|"all") — rank the most similar functions within the binary or across instances; returns a per-signal breakdown and confidence label.
• compare_functions(a, b) — direct pairwise similarity between two functions (optionally across instances).

Instance IDs Explained

Instance IDs are 4-character base36 strings (0-9, a-z) like k7m2, px3a, 9bf1.

Why 4 characters?

• Short and readable
• 1.68 million combinations (collision-free for typical use)
• Auto-expands to 5 characters if collision detected

How are they generated?

• Based on: process ID, port, and IDB file path
• Same binary reopened = same ID (deterministic)
• Binary replaced/changed = new ID (automatic)

What happens when you change binaries? When you open a different binary in an IDA instance:

1. Old instance expires (e.g., k7m2 → expired)
2. New instance registers (e.g., b12)
3. If LLM tries to use old ID, you get a helpful error with the replacement ID

CLI Commands

ida-multi-mcp

Start the MCP server (stdio). Used by MCP clients. This is the default command.

ida-multi-mcp
ida-multi-mcp --idalib-python /path/to/python3  # custom Python for headless sessions

ida-multi-mcp --list

List all registered IDA instances.

ida-multi-mcp --list

ida-multi-mcp --install [--ida-dir DIR]

Install the IDA plugin and auto-configure all detected MCP clients (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Zed, and 20+ more).

ida-multi-mcp --install
ida-multi-mcp --install --ida-dir "C:\Program Files\IDA Pro 9.0"  # Windows custom path

ida-multi-mcp --uninstall [--ida-dir DIR]

Remove the IDA plugin, clean up registry, and remove MCP client configurations.

ida-multi-mcp --uninstall

ida-multi-mcp --config

Print the MCP client configuration JSON for easy reference.

ida-multi-mcp --config

Architecture

Instance Registry

Location:

• macOS/Linux: ~/.ida-mcp/instances.json
• Windows: %USERPROFILE%\.ida-mcp\instances.json

Each registered instance includes:

• id — 4-char instance identifier (k7m2, px3a, etc.)
• pid — Process ID of the IDA Pro instance
• host — Always 127.0.0.1 (localhost)
• port — Dynamically assigned HTTP port
• binary_name — Filename (malware.exe, driver.dll, etc.)
• binary_path — Full path to binary
• arch — Architecture (x86_64, x86, arm64, etc.)
• registered_at — Timestamp when instance registered
• last_heartbeat — Last heartbeat check timestamp

IDA Plugin Directory

• macOS/Linux: ~/.idapro/plugins/
• Windows: %APPDATA%\Hex-Rays\IDA Pro\plugins\

Request Routing

1. MCP client calls a tool (e.g., decompile) with required instance_id parameter
2. Server routes to the target instance via HTTP JSON-RPC
3. IDA instance processes the request
4. Result returned to client

Health Monitoring

• Each IDA instance sends a heartbeat every 60 seconds
• Stale instances (no heartbeat for 2+ minutes) are automatically cleaned up
• On server startup, dead processes are removed from the registry
• If an instance crashes, subsequent requests get a helpful error message

Binary Change Detection

Uses dual-strategy detection:

Primary (Fast) — IDA event hooks trigger immediately when binary changes Fallback (Safe) — Every tool call verifies binary hasn’t changed, handles hook failures

When a binary change is detected:

• Old instance ID is marked as expired
• New instance registers with new ID
• LLM receives helpful message with replacement ID

Troubleshooting

Design Decisions

Performance

Benchmarked against a large game client (736K functions, x86-64, IDA 9.3):

Infrastructure overhead:

• Registry operations: <1ms (JSON file, file-locked)
• Tool discovery: ~50ms per IDA instance (one-time cache)
• Tool call routing: <5ms (local HTTP JSON-RPC)
• Heartbeat interval: 60 seconds (negligible overhead)

Full benchmark report with per-tool detail →

Limitations

• Supports 127.0.0.1 only (localhost analysis)
• Remote IDA instances not supported in v1.0
• Headless (idalib) mode requires IDA Pro — IDA Home/Free do not include idalib.dll
• Resources (not tools) require manual routing in v1.0

License

MIT

Contributing

Contributions welcome! Please ensure:

• Python 3.11+ compatibility
• Cross-platform (Windows, macOS, Linux)
• Clean, readable code
• Tests for new features

Acknowledgments

This project was inspired by and builds upon ida-pro-mcp by Duncan Ogilvie (mrexodia). The IDA tool implementations (80+ tools) originated from ida-pro-mcp and have been absorbed into ida-multi-mcp as a bundled package, adding multi-instance orchestration and headless idalib support on top.

The installation approach (AI-agent-friendly installation guides) was influenced by oh-my-opencode by Yeongyu Yun (code-yeongyu).

Related Projects

• ida-pro-mcp — The original single-instance IDA MCP plugin (tools originated from here) (MIT License)
• Claude Code — MCP client with native support
• Cursor — Alternative MCP-enabled editor

Support

For issues, feature requests, or questions:

• Check the troubleshooting section above
• Review docs/.ssot/architectures/ for architecture details
• Open an issue on GitHub

Star History