IDA‑instances‑MCP – a stable, multi‑instance MCP server for IDA Pro

What it is

• A custom fork of ida‑pro‑mcp that runs a Model‑Context‑Protocol (MCP) server allowing AI‑powered tools (Claude Code, Cursor, VS Code extensions, etc.) to control IDA Pro programmatically.
• Adds a “headless‑instances” layer so many IDA workers can run in parallel, each with its own isolated database, all behind a single HTTP (or stdio) endpoint.

Key improvements over upstream

Area	Improvement
Data safety	Won’t delete .id0/.id1/.id2/.nam/.til files that belong to another live session.
Save reliability	idb_save gets a 10‑minute budget; failed saves no longer discard changes.
Concurrency	Supervisor lock no longer blocks the whole server while a worker starts or is cleaned up.
Robustness	Malformed JSON‑RPC now returns proper error codes instead of crashing.
Timeouts	Proxy timeout raised to 15 min (configurable) so long decompilations finish.
Networking	Port‑race handling, locked SSE writes, cached CORS reads.
Resource limits	Trace logs capped at 64 MiB, oversized args/results clipped, bounded failure queue.
Authentication	Every HTTP request must present a one‑time‑issued API key (GET /key).
Management endpoints	/health, /sessions, /upload (binary upload, size‑capped).
Idle reaping	Sessions idle > IDA_MCP_IDLE_TIMEOUT min are auto‑saved and closed.
Graceful shutdown	All open databases are saved on SIGTERM/SIGINT.
Self‑update	Checks GitHub releases on start and can auto‑update with a keystroke.
Defaults	Listens on 0.0.0.0:9999; GUI plugin also binds to 0.0.0.0 and uses the same API key.

How it works

1. Supervisor (idalib-mcp) runs as a lightweight HTTP server. It spawns a separate worker process for each opened IDB, each loading IDA’s idalib in head‑less mode.
2. Clients speak MCP (JSON‑RPC) over HTTP (or stdio). The supervisor forwards calls to the appropriate worker, enforces time‑outs, and returns results.
3. An API key generated at start protects every endpoint; the key is stored at ~/.idapro/mcp/api_key and survives restarts.

Typical workflow

# 1️⃣ Activate IDA’s Python environment (uv is the recommended package manager)
uv run "/opt/idapro-9.x/idalib/python/py-activate-idalib.py"

# 2️⃣ Start the headless MCP server (default binds 0.0.0.0:9999)
uv run idalib-mcp

# 3️⃣ Retrieve the one‑time API key
KEY=$(curl -s http://host:9999/key | jq -r .key)

# 4️⃣ Upload a binary for analysis
curl -H "Authorization: Bearer $KEY" \
     --data-binary @sample.elf \
     "http://host:9999/upload?filename=sample.elf"

# 5️⃣ Point an MCP‑aware client (e.g., Claude Code) at the server using the same key.

Running the interactive GUI proxy

• Install the MCP plugin inside IDA (Edit → Plugins → MCP).
• From a terminal: uv run ida-pro-mcp (stdio) or uv run ida-pro-mcp --transport http://127.0.0.1:9999 to expose the same HTTP API while you work in the full IDA UI.

Configuration (environment variables, command‑line flags)

• IDA_MCP_MAX_WORKERS – max concurrent IDA instances (default 4, 0 = unlimited).
• IDA_MCP_IDLE_TIMEOUT – minutes of inactivity before a session is auto‑closed (default 60).
• IDA_MCP_PROXY_TIMEOUT – timeout for calls from the GUI proxy to the worker (default 900 s).
• IDA_MCP_API_KEY / IDA_MCP_API_KEY_FILE – inject a pre‑generated key.
• Various other knobs control open‑time limits, upload size caps, health‑probe budgets, etc.

Use cases

• AI‑assisted reverse engineering: let Claude Code, Cursor, or other LLM‑driven agents run IDA analyses (decompilation, symbol renaming, CFG extraction) without a human‑present UI.
• Batch analysis farm: spin up dozens of headless IDA workers on a server, each handling a separate binary, all orchestrated via MCP.
• CI/CD security scans: integrate the server into pipelines that automatically upload binaries, run static analysis tools inside IDA, and retrieve results.

Testing The repo ships a ida-mcp-test helper; examples show how to run it against sample ELF binaries with different analysis categories.

License

• MIT (inherited from the upstream ida-pro-mcp).
• Requires a valid commercial IDA Pro license; the free version is not supported.

---

This summary is based solely on the repository’s README.