Skip to content
Back to search

IDA-instances-MCP

Custom build of ida-pro-mcp - stability-hardened MCP server for hosting headless IDA Pro instances

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/claude-reverser--ida-instances-mcp/badge.svg)](/listings/claude-reverser--ida-instances-mcp)

HTML

<a href="/listings/claude-reverser--ida-instances-mcp"><img src="/api/listings/claude-reverser--ida-instances-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

Run the headless supervisor (hosting mode)

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.

Hosting endpoints

| Endpoint | Auth | Purpose | |----------|------|---------| | `GET /health` | none | Readiness probe: `{"status":"ok","uptime":N,"sessions":N}` — poll instead of sleeping | | `GET /sessions` | key | Open databases incl. last-accessed timestamps | | `POST /upload?filename=NAME` | key | Raw-body binary upload, streamed to `IDA_MCP_UPLOAD_DIR`; returns the path to feed `idb_open` |

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

Run the GUI proxy (interactive IDA)

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

Connect an MCP client

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 187 lines · 2 findings marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # IDA-instances-MCP
  2. Custom build of [ida-pro-mcp](https://github.com/mrexodia/ida-pro-mcp): an
  3. [MCP Server](https://modelcontextprotocol.io/introduction) that lets MCP clients
  4. drive IDA Pro — reworked with a stability pass aimed at hosting **multiple
  5. headless idalib instances** (the Ida-Instances setup).
  6. This is a fork of mrexodia's `ida-pro-mcp` (MIT). All upstream credit goes to
  7. [Duncan Ogilvie](https://github.com/mrexodia) and contributors; the custom
  8. changes below are maintained in this repository.
  9. ## What's custom
  10. Stability hardening on top of upstream v2.0.0:
  11. | Area | Change |
  12. |------|--------|
  13. | Data safety | Partial-database cleanup is ownership-aware: it never deletes `.id0/.id1/.id2/.nam/.til` files claimed by another live instance, and fails safe when discovery is unavailable |
  14. | Save reliability | `idb_save` runs with a 600s budget (was 60s); `idb_close` refuses to kill a worker after a failed save instead of silently discarding changes |
  15. | Concurrency | Supervisor lock no longer spans worker spawn (~120s), health probes (~2.5s/session) or stale-worker termination — one slow open can't freeze every session |
  16. | Robustness | Malformed JSON-RPC over stdio returns `-32700`/`-32600` instead of crashing the proxy |
  17. | Timeouts | Proxy timeout raised 30s → 900s and made configurable (`IDA_MCP_PROXY_TIMEOUT`) so long decompiles don't "fail" client-side while still running server-side |
  18. | Networking | Worker port TOCTOU now retries; SSE writes and teardown are lock-guarded; CORS policy reads are cached off the IDA main thread |
  19. | Resource limits | IDB trace log capped at 64 MB (`IDA_MCP_TRACE_MAX_MB`) with oversized arguments/results clipped; flush-failure queue bounded |
  20. | Authentication | Every HTTP request requires an instance API key; issued **exactly once** via `GET /key`, then burned. The key persists on disk so it survives restarts and reboots |
  21. | Hosting endpoints | `GET /health` (unauthenticated readiness probe), `GET /sessions` (open databases + last-accessed), `POST /upload` (direct binary upload with size cap) |
  22. | Idle reaping | Sessions untouched for `IDA_MCP_IDLE_TIMEOUT` minutes are auto-closed (saved first) |
  23. | Graceful shutdown | On `SIGTERM`/`SIGINT` every open database is saved before exit — no more lost work on `pct stop` |
  24. | Self-update | Startup checks GitHub releases; interactive sessions are offered a one-keypress auto-update |
  25. | Hosting defaults | Headless supervisor listens on **0.0.0.0:9999**; the GUI plugin also binds **0.0.0.0** and now requires the same API key |
  26. ## Requirements
  27. - Linux, macOS or Windows
  28. - [Python](https://www.python.org/downloads/) **3.11+** (use `idapyswitch` inside IDA to match)
  29. - [IDA Pro](https://hex-rays.com/ida-pro) **8.3+** (9.x recommended). **IDA Free is not supported**
  30. - [uv](https://astral.sh/uv)
  31. - An MCP client (Claude Code, Cursor, Codex, Opencode, VS Code, ...)
  32. ## Setup
  33. Activate idalib for your uv environment:
  34. ```bash
  35. # linux (server deployment)
  36. uv run "/opt/idapro-9.x/idalib/python/py-activate-idalib.py"
  37. # macos
  38. uv run "/Applications/IDA Professional 9.x.app/Contents/MacOS/idalib/python/py-activate-idalib.py"
  39. # windows
  40. uv run "C:\Program Files\IDA Professional 9.x\idalib\python\py-activate-idalib.py"
  41. ```
  42. Headless runs additionally need the IDA install directory in `IDADIR`.
  43. ### Run the headless supervisor (hosting mode)
  44. ```bash
  45. uv run idalib-mcp # serves http://0.0.0.0:9999/mcp (new default)
  46. ```
  47. On startup an **API key** is generated (or loaded from disk) and every request
  48. without it gets `401 Unauthorized` — no exceptions.
  49. Fetch the key once, from the machine/network that owns the instance:
  50. ```bash
  51. curl http://your-host:9999/key
  52. # {"key": "3f2b..."} <- save it; this endpoint is now burned until restart
  53. ```
  54. - The key persists at `~/.idapro/mcp/api_key` (mode `0600`) and survives
  55. reboots; `GET /key` re-issues it once per server start
  56. - Override with `IDA_MCP_API_KEY` (or relocate via `IDA_MCP_API_KEY_FILE`)
  57. - All other endpoints require it on every call:
  58. ```
  59. Authorization: Bearer <key>
  60. # or equivalently
  61. X-API-Key: <key>
  62. ```
  63. The key is never logged.
  64. #### Hosting endpoints
  65. | Endpoint | Auth | Purpose |
  66. |----------|------|---------|
  67. | `GET /health` | none | Readiness probe: `{"status":"ok","uptime":N,"sessions":N}` — poll instead of sleeping |
  68. | `GET /sessions` | key | Open databases incl. last-accessed timestamps |
  69. | `POST /upload?filename=NAME` | key | Raw-body binary upload, streamed to `IDA_MCP_UPLOAD_DIR`; returns the path to feed `idb_open` |
  70. ```bash
  71. # provisioning flow
  72. while ! curl -sf http://10.0.0.4:9999/health >/dev/null; do sleep 1; done
    • Dismissed after review: Fetches a raw IP-literal URL — ambiguous (could be legitimate internal tooling) but worth a second look
    • Line 94 on GitHub
  73. KEY=$(curl -s http://10.0.0.4:9999/key | jq -r .key)
    • Warning: Fetches a raw IP-literal URL — ambiguous (could be legitimate internal tooling) but worth a second look
    • Line 95 on GitHub
  74. curl -H "Authorization: Bearer $KEY" --data-binary @sample.elf \
  75. "http://10.0.0.4:9999/upload?filename=sample.elf"
  76. ```
  77. Useful flags:
  78. ```bash
  79. uv run idalib-mcp --host 127.0.0.1 --port 9999 # override bind address
  80. uv run idalib-mcp --max-workers 8 # concurrent databases (default 4, 0 = unlimited)
  81. uv run idalib-mcp --unsafe # enable destructive/debugger tools (DANGEROUS)
  82. uv run idalib-mcp --profile tools.txt # restrict worker tools to a profile file
  83. uv run idalib-mcp --stdio # stdio transport instead of HTTP
  84. uv run idalib-mcp path/to/binary # open a binary at startup
  85. ```
  86. Session lifecycle tools: `idb_open`, `idb_list`, `idb_close` — open one database
  87. per session; each session gets its own isolated worker process.
  88. ### Run the GUI proxy (interactive IDA)
  89. Start the plugin inside IDA (`Edit -> Plugins -> MCP`, or `Ctrl+Alt+M`), then:
  90. ```bash
  91. uv run ida-pro-mcp # stdio proxy, auto-discovers IDA
  92. uv run ida-pro-mcp --transport http://127.0.0.1:9999 # serve HTTP instead
  93. ```
  94. ### Connect an MCP client
  95. Generic JSON config (HTTP transport):
  96. ```json
  97. {
  98. "mcpServers": {
  99. "ida-instances": {
  100. "url": "http://your-host:9999/mcp",
  101. "headers": {
  102. "Authorization": "Bearer <key-from-/key>"
  103. }
  104. }
  105. }
  106. }
  107. ```
  108. Claude Code:
  109. ```bash
  110. claude mcp add --transport http ida-instances http://your-host:9999/mcp \
  111. --header "Authorization: Bearer <key-from-/key>"
  112. ```
  113. For the GUI proxy over stdio, run `uv run ida-pro-mcp --config` and paste the
  114. JSON into your client.
  115. ## Configuration (environment variables)
  116. | Variable | Default | Meaning |
  117. |----------|---------|---------|
  118. | `IDA_MCP_OPEN_TIMEOUT` | `1800` | Max seconds for open + auto-analysis before reap (`0` = unlimited) |
  119. | `IDA_MCP_WORKER_CALL_TIMEOUT` | `900` | Backstop per forwarded tool call |
  120. | `IDA_MCP_PROXY_TIMEOUT` | `900` | GUI-proxy → IDA upstream timeout (`0` = unlimited) |
  121. | `IDA_MCP_TRACE_MAX_MB` | `64` | Trace log cap stored inside the IDB |
  122. | `IDA_MCP_MAX_WORKERS` | `4` | Default `--max-workers` |
  123. | `IDA_MCP_HEALTH_TCP_TIMEOUT` / `IDA_MCP_HEALTH_RPC_TIMEOUT` | `2.0` / `10.0` | Health probe budgets |
  124. | `IDA_MCP_IDLE_TIMEOUT` | `60` | Minutes before an untouched session is auto-closed (`0` disables) |
  125. | `IDA_MCP_MAX_UPLOAD_MB` | `100` | Cap for `POST /upload` bodies |
  126. | `IDA_MCP_UPLOAD_DIR` | `~/.idapro/mcp/uploads` | Where uploads are stored |
  127. | `IDA_MCP_API_KEY` / `IDA_MCP_API_KEY_FILE` | – / `~/.idapro/mcp/api_key` | Inject or relocate the instance key |
  128. | `IDA_MCP_SHUTDOWN_SAVE_TIMEOUT` / `IDA_MCP_SHUTDOWN_SAVE_BUDGET` | `30` / `120` | Per-database / total save budget on SIGTERM |
  129. | `IDA_MCP_NO_UPDATE_CHECK` | unset | Set `1` to disable the GitHub release check |
  130. > **Security notes:** the API key gates every HTTP endpoint on both the
  131. > supervisor and the GUI plugin (the plugin can execute arbitrary code via
  132. > `py_eval`, so it is keyed even on loopback). It is a bearer token — anyone
  133. > who obtains it owns the instance; add a TLS reverse proxy if it leaves your
  134. > trusted network. Browsers can pass the key as `?key=<key>` (handy for
  135. > `/config.html`).
  136. ## Testing
  137. ```bash
  138. IDADIR=/path/to/ida uv run ida-mcp-test tests/crackme03.elf -q
  139. IDADIR=/path/to/ida uv run ida-mcp-test tests/typed_fixture.elf -q
  140. IDADIR=/path/to/ida uv run ida-mcp-test tests/crackme03.elf -c api_analysis # one category
  141. IDADIR=/path/to/ida uv run coverage run -m ida_pro_mcp.test tests/crackme03.elf -q
  142. ```
  143. ## License
  144. MIT — inherited from upstream [`ida-pro-mcp`](https://github.com/mrexodia/ida-pro-mcp).
  145. Upstream product names (IDA Pro, Hex-Rays) are trademarks of Hex-Rays SA; this
  146. project requires your own valid IDA Pro license.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.