Custom build of ida-pro-mcp: an MCP Server that lets MCP clients drive IDA Pro — reworked with a stability pass aimed at hosting multiple headless idalib instances (the Ida-Instances setup).

This is a fork of mrexodia's ida-pro-mcp (MIT). All upstream credit goes to Duncan Ogilvie and contributors; the custom changes below are maintained in this repository.

Stability hardening on top of upstream v2.0.0:

• Linux, macOS or Windows
• Python 3.11+ (use idapyswitch inside IDA to match)
• IDA Pro 8.3+ (9.x recommended). IDA Free is not supported
• uv
• An MCP client (Claude Code, Cursor, Codex, Opencode, VS Code, ...)

Activate idalib for your uv environment:

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

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

On startup an API key is generated (or loaded from disk) and every request without it gets 401 Unauthorized — no exceptions.

Fetch the key once, from the machine/network that owns the instance:

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

• The key persists at ~/.idapro/mcp/api_key (mode 0600) and survives reboots; GET /key re-issues it once per server start
• Override with IDA_MCP_API_KEY (or relocate via IDA_MCP_API_KEY_FILE)
• All other endpoints require it on every call:

Authorization: Bearer <key>
# or equivalently
X-API-Key: <key>

The key is never logged.

# provisioning flow
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"

Useful flags:

uv run idalib-mcp --host 127.0.0.1 --port 9999   # override bind address
uv run idalib-mcp --max-workers 8                # concurrent databases (default 4, 0 = unlimited)
uv run idalib-mcp --unsafe                       # enable destructive/debugger tools (DANGEROUS)
uv run idalib-mcp --profile tools.txt            # restrict worker tools to a profile file
uv run idalib-mcp --stdio                        # stdio transport instead of HTTP
uv run idalib-mcp path/to/binary                 # open a binary at startup

Session lifecycle tools: idb_open, idb_list, idb_close — open one database per session; each session gets its own isolated worker process.

Start the plugin inside IDA (Edit -> Plugins -> MCP, or Ctrl+Alt+M), then:

uv run ida-pro-mcp                                   # stdio proxy, auto-discovers IDA
uv run ida-pro-mcp --transport http://127.0.0.1:9999 # serve HTTP instead

Generic JSON config (HTTP transport):

{
  "mcpServers": {
    "ida-instances": {
      "url": "http://your-host:9999/mcp",
      "headers": {
        "Authorization": "Bearer <key-from-/key>"
      }
    }
  }
}

Claude Code:

claude mcp add --transport http ida-instances http://your-host:9999/mcp \
  --header "Authorization: Bearer <key-from-/key>"

For the GUI proxy over stdio, run uv run ida-pro-mcp --config and paste the JSON into your client.

Security notes: the API key gates every HTTP endpoint on both the supervisor and the GUI plugin (the plugin can execute arbitrary code via py_eval, so it is keyed even on loopback). It is a bearer token — anyone who obtains it owns the instance; add a TLS reverse proxy if it leaves your trusted network. Browsers can pass the key as ?key=<key> (handy for /config.html).

IDADIR=/path/to/ida uv run ida-mcp-test tests/crackme03.elf -q
IDADIR=/path/to/ida uv run ida-mcp-test tests/typed_fixture.elf -q
IDADIR=/path/to/ida uv run ida-mcp-test tests/crackme03.elf -c api_analysis   # one category
IDADIR=/path/to/ida uv run coverage run -m ida_pro_mcp.test tests/crackme03.elf -q

MIT — inherited from upstream ida-pro-mcp. Upstream product names (IDA Pro, Hex-Rays) are trademarks of Hex-Rays SA; this project requires your own valid IDA Pro license.