IDA-instances-MCP: a hardened ida-pro-mcp fork for headless IDA Pro instances

The problem: one IDA window, one analysis at a time

Upstream ida-pro-mcp connects an MCP client to a single running IDA Pro instance, usually through a plugin inside the GUI. That works when a person is sitting in front of IDA. It stops working when you want an agent, a script, or a queue of binaries to drive analysis without a desktop session. IDA-instances-MCP is a fork of mrexodia's ida-pro-mcp, kept at version 2.0.0 in pyproject.toml, that reworks the server around hosting multiple headless idalib instances instead. The README calls this the Ida-Instances setup and frames the changes as a stability pass rather than a feature expansion.

The audience is narrow and specific. You need IDA Pro 8.3 or newer (9.x is recommended), Python 3.11 or newer, and uv. The README states plainly that IDA Free is not supported, which is the single hardest gate in the project. If you do not hold an IDA Pro licence, nothing else in this article applies to you. If you do, the fork targets the case where several databases are open at once and each one gets its own isolated worker process.

It is worth being clear about what this is not. It is not a decompiler, not a loader, and not a replacement for IDA's analysis engine. Every disassembly, decompilation and type recovery result you get back still comes from IDA Pro through idalib. The fork only changes how sessions are hosted, authenticated and torn down around that engine.

Installing it and opening your first database

The first step is not installation in the usual sense. idalib ships inside IDA Pro, and the README instructs you to activate it for your uv environment with the py-activate-idalib.py script from your IDA install. The path differs per platform, and the README gives all three:

# linux (server deployment)
uv run "/opt/idapro-9.x/idalib/python/py-activate-idalib.py"
# macos
uv run "/Applications/IDA Professional 9.x.app/Contents/MacOS/idalib/python/py-activate-idalib.py"
# windows
uv run "C:\Program Files\IDA Professional 9.x\idalib\python\py-activate-idalib.py"

Headless runs additionally need the IDA install directory in IDADIR. After activation you start the supervisor, which on first run generates an API key and begins serving on port 9999.

uv run idalib-mcp                # serves http://0.0.0.0:9999/mcp (new default)

The key is the part people miss. Every HTTP request needs it, and GET /key issues it exactly once per server start and then burns. Fetch it from the machine or network that owns the instance and store it, because the endpoint will not answer again until restart. It persists at ~/.idapro/mcp/api_key with mode 0600, so it survives reboots, and IDA_MCP_API_KEY or IDA_MCP_API_KEY_FILE can override or relocate it.

curl http://your-host:9999/key
# {"key": "3f2b..."}   <- save it; this endpoint is now burned until restart

With the key in hand, point an MCP client at the endpoint. The README gives a generic JSON block for HTTP transport, and a Claude Code one-liner that adds the server with an Authorization header. The hosting flow the README demonstrates is a readiness loop against GET /health, which needs no authentication, followed by a key fetch and a binary upload.

while ! curl -sf http://10.0.0.4:9999/health >/dev/null; do sleep 1; done
KEY=$(curl -s http://10.0.0.4:9999/key | jq -r .key)
curl -H "Authorization: Bearer $KEY" --data-binary @sample.elf \
     "http://10.0.0.4:9999/upload?filename=sample.elf"

POST /upload streams the raw body to IDA_MCP_UPLOAD_DIR and returns the path to feed to idb_open. That is the provisioning path: health check, key, upload, open. Useful flags the README lists include --host and --port to override the bind address, --max-workers to set concurrency, --profile to restrict worker tools to a profile file, --stdio for a stdio transport instead of HTTP, and --unsafe to enable destructive and debugger tools. Passing a path to the binary opens it at startup. If you prefer the interactive route, start the plugin inside IDA through Edit -> Plugins -> MCP or Ctrl+Alt+M, then run uv run ida-pro-mcp for a stdio proxy that auto-discovers IDA, or uv run ida-pro-mcp --transport http://127.0.0.1:9999 to serve HTTP.

Where the hardening stops short

The security model is a single bearer key with no rotation story. GET /key is burned after one fetch, which is good against a casual snooper on the network, but the key then lives on disk at ~/.idapro/mcp/api_key and is reused across restarts. There is no documented revocation, no per-client key, and no expiry. If the file leaks, the holder has full access to every session until an operator deletes it and restarts. The README says the key is never logged, which is a real property, but it does not describe how to rotate one.

The bind address is the other sharp edge. The README lists 0.0.0.0:9999 as the hosting default and notes that the GUI plugin also binds 0.0.0.0 and requires the same key. The --host flag exists to override it, and the README shows 127.0.0.1 as an example, but the default is not loopback. Anyone deploying this on a machine with a public interface is exposing an endpoint that can open binaries, run analysis and, with --unsafe, reach destructive and debugger tools. The README labels that flag DANGEROUS in capitals. Treat the default as a deployment decision, not an accident.

There is also a resource ceiling worth knowing. The IDB trace log is capped at 64 MB by IDA_MCP_TRACE_MAX_MB, and oversized arguments and results are clipped. That protects the server, but it means a very large trace or a very large tool result will be truncated rather than delivered. If your workflow depends on complete trace output, the cap is a limit, not a bug you can ignore. The flush-failure queue is bounded as well, so a persistently failing flush does not grow without limit; what happens to the queued entries in that case is not spelled out in the README.

Finally, the failure mode that remains is process-level. Worker isolation means one crashed worker should not take the supervisor down with it, but the README does not describe what a client sees when a worker dies mid-call, beyond the per-call backstop timeout. If you build automation on top of this, plan for a call that times out and has to be retried rather than assuming every tool call returns.

Maintenance, packaging and upgrade cost

The repository is not archived, and the last push was on 2026-08-23. There are no releases retrieved for it, so distribution is from the repository itself rather than a published artefact. The package is named ida-instances-mcp at version 2.0.0, requires Python 3.11 or newer, and depends on idapro>=0.0.9 and tomli-w>=1.0.0. Development dependencies include pytest, coverage, jsonschema and mcp. The build backend is setuptools, and four console scripts are declared: ida-pro-mcp, idalib-mcp, ida-mcp-test and ida-mcp-trace-dump. The presence of tests/ and a coverage configuration that includes src/ida_pro_mcp/* suggests the fork carries its own test surface, though the README does not describe how to run it.

Upgrade cost is the interesting part. The README describes a self-update mechanism: startup checks GitHub releases, and interactive sessions are offered a one-keypress auto-update. That is convenient for a workstation and awkward for a server, where an unattended process checking releases and offering an update is a change you want to control deliberately. The environment variables are the other upgrade surface. IDA_MCP_PROXY_TIMEOUT, IDA_MCP_TRACE_MAX_MB, IDA_MCP_MAX_WORKERS, IDA_MCP_IDLE_TIMEOUT and the health probe budgets all have defaults that changed relative to upstream, so a deployment carried over from upstream may behave differently without any config edit. If you migrate, diff the environment against the table in the README rather than assuming the defaults carried over.

On licensing: the project is MIT, and the README credits mrexodia's ida-pro-mcp, also MIT, with upstream credit to Duncan Ogilvie and contributors. MIT covers the code in this repository. It does not cover IDA Pro itself, which is commercial software from Hex-Rays with its own terms, and the README says nothing about whether a given IDA licence permits headless idalib deployment on a server. That is a question for your licence holder, not for the repository.

Editorial conclusion

Adopt it if you already run IDA Pro 8.3+ under a licence that permits headless idalib use and you need several concurrent analysis sessions behind one authenticated HTTP endpoint. Do not adopt it if you only use IDA Free, if you rely on the upstream GUI proxy and nothing else, or if you cannot accept that the API key is issued exactly once per server start and then burned. Before wiring it into anything, verify that py-activate-idalib.py binds the idalib Python package into your uv environment, confirm the supervisor is reachable on 0.0.0.0:9999 behind whatever network boundary you control, and check whether your IDA licence covers unattended server deployment, because the README says nothing about licensing terms for headless use.

Frequently asked questions

Official sources

1. Claude-Reverser/IDA-instances-MCP on GitHub
2. Issues
3. License: MIT
4. README