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).

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.

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.

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)

• 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
• 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

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

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

Pick your platform:

Python> import sys; print(sys.version)

# 1. Install CLI tool via pipx (for terminal commands)
pipx install git+https://github.com/MeroZemory/ida-multi-mcp.git

# 2. Install package for IDA's Python (replace 3.11 with your IDA's version)
python3.11 -m pip install --user git+https://github.com/MeroZemory/ida-multi-mcp.git

# 3. Install IDA plugin + configure MCP clients
ida-multi-mcp --install

# 4. Configure Claude Code manually (recommended over --install for Claude Code)
claude mcp add ida-multi-mcp -s user -- ida-multi-mcp

# 0. (Recommended) Clean previous install to avoid stale scripts/config
ida-multi-mcp --uninstall
python -m pip uninstall -y ida-multi-mcp

# 1. Install ida-multi-mcp
python -m pip install git+https://github.com/MeroZemory/ida-multi-mcp.git

# 2. Install IDA plugin + configure all MCP clients
ida-multi-mcp --install

# 1. Install ida-multi-mcp
pip install --user git+https://github.com/MeroZemory/ida-multi-mcp.git

# 2. Install IDA plugin + configure MCP clients
ida-multi-mcp --install

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.

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).

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

ida-multi-mcp --config

# 1. Remove IDA plugin + MCP client configurations
ida-multi-mcp --uninstall

# 2. Remove packages
pipx uninstall ida-multi-mcp
python3.11 -m pip uninstall -y ida-multi-mcp  # replace 3.11 with IDA's version

# 1. Remove IDA plugin + MCP client configurations
ida-multi-mcp --uninstall

# (optional) If IDA is installed in a custom location
ida-multi-mcp --uninstall --ida-dir "C:\Program Files\IDA Pro 9.0"

# 2. Remove the Python package
python -m pip uninstall -y ida-multi-mcp

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

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

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

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

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)

The server provides built-in management tools:

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

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

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

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

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

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

List all managed headless idalib sessions.

Health/readiness check for a specific idalib session.

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

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

List all registered IDA instances.

ida-multi-mcp --list

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

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

ida-multi-mcp --uninstall

Print the MCP client configuration JSON for easy reference.

ida-multi-mcp --config

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

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

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

• 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

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

ida-multi-mcp --list

[projects.'\\?\C:\Git\MeroZemory\tidy-up']
trust_level = "trusted"

[mcp_servers.ida-multi-mcp]
command = 'C:\Users\MeroZemory\AppData\Local\Programs\Python\Python311\python.exe'
args = ["-m", "ida_multi_mcp"]

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 →

• 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

MIT

Contributions welcome! Please ensure:

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

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).

• 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

For issues, feature requests, or questions:

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