Skip to content
Back to search

ida-mcp-rs

Headless IDA Pro MCP Server

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/blacktop--ida-mcp-rs/badge.svg)](/listings/blacktop--ida-mcp-rs)

HTML

<a href="/listings/blacktop--ida-mcp-rs"><img src="/api/listings/blacktop--ida-mcp-rs/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.

Install

**macOS / Linux** (via [Homebrew](https://brew.sh))

brew install blacktop/tap/ida-mcp        # Latest (IDA 9.4)

**macOS (Apple Silicon), older IDA releases** (via versioned Homebrew casks)

brew install blacktop/tap/ida-mcp@9.3    # IDA 9.3/9.3sp1
brew install blacktop/tap/ida-mcp@9.2    # IDA 9.2

**Windows** (via [Scoop](https://scoop.sh))

scoop bucket add blacktop https://github.com/blacktop/scoop-bucket
scoop install blacktop/ida-mcp

> **Windows note:** see [Windows](#windows) below for DLL discovery options.

**macOS / Linux** (via [Nix](https://nixos.org))

nix shell github:blacktop/nur#ida-mcp \
  --extra-experimental-features 'nix-command flakes'

**Direct download:** grab the archive for your platform from [GitHub Releases](https://github.com/blacktop/ida-mcp-rs/releases).

**Build from source:** see [docs/BUILDING.md](docs/BUILDING.md).

> ida-mcp versions follow IDA Pro versions: `v9.5.0-beta.x` for the IDA 9.5 beta, `v9.4.x` for IDA 9.4, `v9.3.x` for IDA 9.3, and `v9.2.x` for IDA 9.2. ida-mcp checks compatibility when it initializes IDA. An incompatible version causes IDA-backed tools to fail with an error identifying the detected version and, when available, the loaded library path. Scoop and NUR publish only the latest version. For an older IDA, use the matching [GitHub Release](https://github.com/blacktop/ida-mcp-rs/releases) or, on Apple Silicon, a versioned Homebrew cask.

IDA 9.5 beta

A prerelease build for the IDA 9.5 beta is available for macOS on Apple Silicon:

brew install blacktop/tap/ida-mcp@beta   # IDA 9.5 beta

The beta cask conflicts with the stable `ida-mcp` cask, so remove one before installing the other:

brew uninstall --cask ida-mcp            # switch to the beta
brew uninstall --cask ida-mcp@beta       # switch back to stable

You can also download `ida-mcp_<version>_Darwin_arm64.tar.gz` from the [prerelease on GitHub](https://github.com/blacktop/ida-mcp-rs/releases). There are no beta packages for Linux or Windows; build `main` from source as described in [docs/BUILDING.md](docs/BUILDING.md).

Platform setup

macOS

Standard IDA installs in `/Applications` work without extra setup:

claude mcp add ida -- ida-mcp

If you see `Library not loaded: @rpath/libida.dylib`, point `DYLD_LIBRARY_PATH` at your IDA install:

claude mcp add ida -e DYLD_LIBRARY_PATH='/path/to/IDA.app/Contents/MacOS' -- ida-mcp

Paths found automatically: - `/Applications/IDA Professional 9.4.app/Contents/MacOS` - `/Applications/IDA Pro 9.4.app/Contents/MacOS` - `/Applications/IDA Home 9.4.app/Contents/MacOS` - `/Applications/IDA Essential 9.4.app/Contents/MacOS`

The beta searches the same locations with `9.5` in place of `9.4`.

Linux

The IDA installer defaults to `~/ida-pro-9.4`, and the launcher script looks there:

claude mcp add ida -- ida-mcp

For any other install location, set `IDADIR`:

claude mcp add ida -e IDADIR='/path/to/ida' -- ida-mcp

Lookup order: `$IDADIR`, then `~/ida-pro-9.4`, then `/opt/ida-pro-9.4` and the other RUNPATH fallbacks.

Windows

**Option A:** put `ida-mcp.exe` in your IDA directory. This is the simplest route and needs no environment setup:

# Copy the binary next to ida.dll / idalib.dll
copy ida-mcp.exe "C:\Program Files\IDA Professional 9.4\"
claude mcp add ida -- "C:\Program Files\IDA Professional 9.4\ida-mcp.exe"

**Option B:** install with [Scoop](https://scoop.sh), which finds IDA and sets `IDADIR`:

scoop bucket add blacktop https://github.com/blacktop/scoop-bucket
scoop install blacktop/ida-mcp
claude mcp add ida -- ida-mcp

**Option C:** set `IDADIR` yourself:

$idaDir = "C:\Program Files\IDA Professional 9.4"
[Environment]::SetEnvironmentVariable("IDADIR", $idaDir, "User")
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")

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 · 746 lines

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

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <!--<a href="https://github.com/blacktop/ida-mcp-rs"><img alt="Logo" src="https://raw.githubusercontent.com/blacktop/ida-mcp-rs/refs/heads/main/docs/logo.svg" height="400"/></a>-->
  3. <h1 align="center">ida-mcp-rs</h1>
  4. <h4><p align="center">Headless IDA Pro MCP server for AI-powered reverse engineering.</p></h4>
  5. <p align="center">
  6. <a href="https://github.com/blacktop/ida-mcp-rs/actions" alt="Actions">
  7. <img src="https://github.com/blacktop/ida-mcp-rs/actions/workflows/build.yml/badge.svg" /></a>
  8. <a href="https://github.com/blacktop/ida-mcp-rs/releases/latest" alt="Downloads">
  9. <img src="https://img.shields.io/github/downloads/blacktop/ida-mcp-rs/total.svg" /></a>
  10. <a href="https://github.com/blacktop/ida-mcp-rs/releases" alt="GitHub Release">
  11. <img src="https://img.shields.io/github/v/release/blacktop/ida-mcp-rs" /></a>
  12. <a href="http://doge.mit-license.org" alt="LICENSE">
  13. <img src="https://img.shields.io/:license-mit-blue.svg" /></a>
  14. </p>
  15. <br>
  16. ## Why ida-mcp
  17. - **Built for Apple targets.** Universal Mach-O slice selection, dSYM/DWARF
  18. loading, and dyld_shared_cache module and dylib loading are single tool
  19. calls with explicit parameters, not scripts the agent has to write. In a
  20. measured Claude Code run, selecting and analyzing the x86_64 slice of a
  21. universal binary took one call and about five seconds.
  22. - **Fast and lean.** A native Rust server driving IDA through idalib. The
  23. 28-tool `--profile=lean` cost 25% less than the full set in the
  24. [October 2026 Claude Code benchmark](bench/README.md), with the same task
  25. success rate. The full set is available when you need it.
  26. - **Safe to leave running.** Exact-target edits, `save_idb` checkpoints,
  27. analysis flushed to disk as soon as it finishes, bounded graceful shutdown,
  28. and automatic replacement of crashed or wedged IDA workers.
  29. - **Scriptable when the tools run out.** `run_script` returns a trailing
  30. expression as JSON and keeps state between calls, so one script can find,
  31. filter, and return only what matters.
  32. ## Prerequisites
  33. - Released IDA Pro 9.5 with a valid license and the same host architecture as ida-mcp
  34. - A Hex-Rays decompiler for the target processor when using pseudocode tools
  35. - Working IDAPython when using `run_script`
  36. Open IDA once and complete its first-launch setup, including reviewing and
  37. accepting the license agreement yourself. The 9.5.0 release was validated with
  38. IDA `9.5.261026` on macOS ARM64, Linux ARM64, and Windows ARM64.
  39. ## Getting started
  40. ### Install
  41. **macOS / Linux** (via [Homebrew](https://brew.sh))
  42. ```bash
  43. brew install blacktop/tap/ida-mcp # Latest (IDA 9.5)
  44. ```
  45. **macOS (Apple Silicon), older IDA releases** (via versioned Homebrew casks)
  46. ```bash
  47. brew install blacktop/tap/ida-mcp@9.4 # IDA 9.4
  48. brew install blacktop/tap/ida-mcp@9.3 # IDA 9.3/9.3sp1
  49. brew install blacktop/tap/ida-mcp@9.2 # IDA 9.2
  50. ```
  51. **Windows** (via [Scoop](https://scoop.sh))
  52. ```powershell
  53. scoop bucket add blacktop https://github.com/blacktop/scoop-bucket
  54. scoop install blacktop/ida-mcp
  55. ```
  56. > **Windows note:** see [Windows](#windows) below for DLL discovery options.
  57. **macOS / Linux** (via [Nix](https://nixos.org))
  58. ```bash
  59. nix shell github:blacktop/nur#ida-mcp \
  60. --extra-experimental-features 'nix-command flakes'
  61. ```
  62. **Direct download:** [GitHub Releases](https://github.com/blacktop/ida-mcp-rs/releases/latest)
  63. provides archives for macOS, Linux, and Windows, each for ARM64 and x86_64.
  64. Each release includes `checksums.txt`.
  65. **Build from source:** see [docs/BUILDING.md](docs/BUILDING.md).
  66. > ida-mcp versions follow IDA Pro versions: `v9.5.x` for IDA 9.5, `v9.4.x` for IDA 9.4, `v9.3.x` for IDA 9.3, and `v9.2.x` for IDA 9.2. ida-mcp checks compatibility when it initializes IDA. An incompatible version causes IDA-backed tools to fail with an error identifying the detected version and, when available, the loaded library path. Scoop and NUR publish only the latest version. For an older IDA, use the matching [GitHub Release](https://github.com/blacktop/ida-mcp-rs/releases) or, on Apple Silicon, a versioned Homebrew cask.
  67. #### Upgrading from the IDA 9.5 beta
  68. Install the released IDA 9.5 runtime before switching to the stable server.
  69. The `9.5.261001` beta uses a different Hex-Rays API and can report
  70. `Decompiler not available` with the released SDK. If both installations are
  71. present, make sure the server loads the released runtime.
  72. For Homebrew, replace the beta cask with the stable cask:
  73. ```bash
  74. brew uninstall --cask ida-mcp@beta
  75. brew install blacktop/tap/ida-mcp
  76. ```
  77. ### Platform setup
  78. #### macOS
  79. Standard IDA installs in `/Applications` work without extra setup.
  80. If a library cannot be loaded, or an older IDA install is selected, set
  81. `DYLD_LIBRARY_PATH` for the server process:
  82. ```bash
  83. env DYLD_LIBRARY_PATH='/path/to/IDA.app/Contents/MacOS' ida-mcp --version
  84. ```
  85. Use the same environment setting in your MCP client configuration.
  86. Paths found automatically:
  87. - `/Applications/IDA Professional 9.5.app/Contents/MacOS`
  88. - `/Applications/IDA Pro 9.5.app/Contents/MacOS`
  89. - `/Applications/IDA Home 9.5.app/Contents/MacOS`
  90. - `/Applications/IDA Essential 9.5.app/Contents/MacOS`
  91. #### Linux
  92. Linux release archives contain the `ida-mcp` launcher and `ida-mcp-bin`.
  93. Keep both files in the same directory. The launcher looks for IDA at
  94. `~/ida-pro-9.5` by default.
  95. For another install location, set `IDADIR` for the launcher:
  96. ```bash
  97. env IDADIR='/path/to/ida' ida-mcp --version
  98. ```
  99. The launcher adds that directory to `LD_LIBRARY_PATH`; otherwise the binary's
  100. RUNPATH fallbacks apply. A source-built binary has its preferred IDA path set
  101. at build time. Rebuild it with the desired `IDADIR`, or set `LD_LIBRARY_PATH`
  102. when launching it. See [Building from Source](docs/BUILDING.md#rpath).
  103. #### Windows
  104. **Option A:** put `ida-mcp.exe` in your IDA directory. This is the simplest route and needs no environment setup:
  105. ```powershell
  106. # Copy the binary next to ida.dll / idalib.dll
  107. copy ida-mcp.exe "C:\Program Files\IDA Professional 9.5\"
  108. claude mcp add ida -- "C:\Program Files\IDA Professional 9.5\ida-mcp.exe"
  109. ```
  110. **Option B:** install with [Scoop](https://scoop.sh), which finds IDA and sets `IDADIR`:
  111. ```powershell
  112. scoop bucket add blacktop https://github.com/blacktop/scoop-bucket
  113. scoop install blacktop/ida-mcp
  114. claude mcp add ida -- ida-mcp
  115. ```
  116. **Option C:** set `IDADIR` yourself:
  117. ```powershell
  118. $idaDir = "C:\Program Files\IDA Professional 9.5"
  119. [Environment]::SetEnvironmentVariable("IDADIR", $idaDir, "User")
  120. $userPath = [Environment]::GetEnvironmentVariable("Path", "User")
  121. $pathEntries = @($userPath -split ";" | Where-Object { $_ })
  122. if (-not ($pathEntries -contains $idaDir)) {
  123. [Environment]::SetEnvironmentVariable(
  124. "Path", (@($pathEntries + $idaDir) -join ";"), "User"
  125. )
  126. }
  127. # Then restart your terminal
  128. claude mcp add ida -- ida-mcp
  129. ```
  130. Windows has to find `ida.dll` and `idalib.dll` before `ida-mcp` starts. Putting `ida-mcp.exe` in the IDA directory is the easiest way. Otherwise, set `IDADIR` and add the same directory to `PATH` so the DLLs load at runtime.
  131. Common IDA paths:
  132. - `C:\Program Files\IDA Professional 9.5`
  133. - `C:\Program Files\IDA Pro 9.5`
  134. - `C:\Program Files\IDA Home 9.5`
  135. ### Runtime requirements
  136. The binary links against IDA's libraries at runtime. Baked-in RPATHs cover the standard install paths. For anything else:
  137. | Platform | Library | Fallback Configuration |
  138. |----------|---------|------------------------|
  139. | macOS | `libida.dylib`, `libidalib.dylib` | `DYLD_LIBRARY_PATH` |
  140. | Linux | `libida.so`, `libidalib.so` | `IDADIR` (release launcher) or `LD_LIBRARY_PATH` |
  141. | Windows | `ida.dll`, `idalib.dll` | Place exe in IDA dir, or set `IDADIR` and add IDA dir to `PATH` |
  142. ### Verify the installation
  143. Check the server version, then use `probe` with a binary you want to analyze:
  144. ```bash
  145. ida-mcp --version
  146. mkdir -p ~/ida-work
  147. ida-mcp probe --path /path/to/sample --idb-out ~/ida-work/sample.i64 --list 5
  148. ```
  149. `--version` checks that the executable starts; `probe` also initializes IDA,
  150. opens the input, and reports the loaded runtime. Use `ida-mcp --help` and
  151. `ida-mcp serve-http --help` for the available startup options.
  152. ### Configure your AI agent
  153. #### [Claude Code](https://code.claude.com/docs/en/mcp)
  154. ```bash
  155. claude mcp add ida -- ida-mcp
  156. ```
  157. #### [Codex CLI](https://github.com/openai/codex)
  158. ```bash
  159. codex mcp add ida -- ida-mcp
  160. ```
  161. #### [Gemini CLI](https://github.com/google-gemini/gemini-cli)
  162. ```bash
  163. gemini mcp add ida -- ida-mcp
  164. ```
  165. #### [Cursor](https://cursor.com)
  166. Add to `.cursor/mcp.json`:
  167. ```json
  168. {
  169. "mcpServers": {
  170. "ida": { "command": "ida-mcp" }
  171. }
  172. }
  173. ```
  174. ### Usage
  175. Once your agent is configured, it can drive the tools directly:
  176. ```
  177. # Open one binary. Raw inputs default to analysis disabled.
  178. open_idb(path: "~/samples/malware", idb_out: "~/ida-work/sample.i64")
  179. # Check readiness, then run analysis when functions or xrefs are incomplete
  180. analysis_status()
  181. analyze_funcs(background: true) # returns task_id
  182. task_status(task_id: "analyze-<random>") # poll progress (ID from the analyze_funcs response)
  183. # After analysis completes, inspect functions and resolve a real address
  184. list_functions(limit: 20)
  185. resolve_function(name: "main")
  186. decompile(address: "<address returned by resolve_function>")
  187. strings(limit: 10)
  188. # Discover more tools
  189. tool_catalog(query: "find callers")
  190. # Save edits and release the database when finished
  191. save_idb()
  192. close_idb()
  193. ```
  194. Tools that change the database (`rename`, `set_comments`, `patch`, `patch_asm`,
  195. `apply_types`, `declare_stack`, `delete_stack`, and `lumina_apply`) take exactly
  196. one address or one symbol name. Names must match exactly, case included. A near
  197. miss changes nothing and returns up to eight similar names with their addresses.
  198. A returned `target` record identifies the database, resolved symbol (or `null`),
  199. and requested and effective addresses. Check the operation's result to determine
  200. whether the change succeeded.
  201. For Hex-Rays locals and arguments, use `list_lvars` with one function address
  202. or exact `target_name`. `rename_lvar` and `set_lvar_type` take the same function
  203. selector plus exactly one of `lvar_locator` or `lvar_name`. Prefer the opaque
  204. `locator` returned by `list_lvars`: display names such as `v1` can move to a
  205. different local after a prototype change. A stale or ambiguous locator fails
  206. without making a change. Locals without a locator are edited by exact, unique
  207. name.
  208. The tools return the variable as it was before the edit and the resolved
  209. function target. Use `save_idb` to checkpoint edits to disk.
  210. ```text
  211. list_lvars(target_name: "interesting_function")
  212. rename_lvar(target_name: "interesting_function", lvar_locator: "<locator from list_lvars>", new_name: "count")
  213. set_lvar_type(target_name: "interesting_function", lvar_locator: "<locator from list_lvars>", decl: "unsigned int")
  214. save_idb()
  215. ```
  216. `list_lvars` is in the `decompile` toolset, `rename_lvar` in `editing`, and
  217. `set_lvar_type` in `types`. Add them to lean with
  218. `--profile=lean --tools=list_lvars,rename_lvar,set_lvar_type`.
  219. For end-of-line comments in Hex-Rays pseudocode, use
  220. `list_pseudocode_comments` with one function address or exact `target_name`.
  221. It returns each commentable line's opaque `locator`, address, text, and
  222. existing comment, paginated like `list_lvars`. Pass one `locator` to
  223. `set_pseudocode_comment` as `comment_locator`; an empty comment removes it. A stale locator fails
  224. without making a change; list the locations again after reanalysis.
  225. `set_comments` edits disassembly comments, which pseudocode does not show.
  226. ```text
  227. list_pseudocode_comments(target_name: "interesting_function")
  228. set_pseudocode_comment(target_name: "interesting_function", comment_locator: "<locator from list_pseudocode_comments>", comment: "validated input")
  229. save_idb()
  230. ```
  231. `list_pseudocode_comments` is in the `decompile` toolset and
  232. `set_pseudocode_comment` in `editing`.
  233. ## Opening binaries
  234. ### Raw blobs
  235. Raw inputs use IDA's normal loader by default and save to `<input>.i64`. Pass
  236. `idb_out` to put the database somewhere else, for example when the input
  237. directory is read-only. An existing database is reused only when the input
  238. SHA-256 recorded in it matches the current file. `rebuild: true` overwrites a
  239. database only when its recorded hash or input path shows it was built from this
  240. input.
  241. For headerless blobs, `open_idb` also takes typed loader hints:
  242. ```text
  243. open_idb(
  244. path: "~/firmware/boot.bin",
  245. idb_out: "~/ida-work/boot.i64",
  246. processor: "arm:ARMv7-M",
  247. bitness: 32,
  248. base_address: "0x08000000",
  249. entry_point: "0x08000101"
  250. )
  251. ```
  252. Processor families with several modes need an explicit IDA processor variant,
  253. so bare names such as `arm` or `metapc` are rejected. The hints apply only when
  254. creating a database from a raw input; they never change an existing
  255. `.i64`/`.idb`. On 32-bit ARM, an odd `entry_point` is a Thumb pointer: ida-mcp
  256. clears bit 0 for the code address and records the Thumb state before creating
  257. the entry instruction.
  258. ### Universal (fat) Mach-O
  259. When IDA loads a fat binary headlessly, it takes the x86_64 slice whenever one
  260. exists, and it doesn't recognize 64-bit fat headers at all. So `open_idb` picks
  261. the slice itself. Pass `arch` (for example `arm64e` or `x86_64`), or leave it out
  262. and answer the prompt if your client supports input requests.
  263. If no answer comes back, the call fails and lists the slices so an unattended
  264. agent can retry with `arch`. That covers clients that can't prompt, a declined
  265. prompt, and pre-2026 clients that don't reply within 30 seconds. MCP 2026
  266. clients get the question back in the response and retry with the answer, so
  267. the server never sits waiting on them.
  268. The chosen slice is copied to `<input name>.<arch>` next to the output database
  269. and opened as a single-architecture Mach-O. An identical copy already at that
  270. path is reused; a different file there is never overwritten. The response's
  271. `universal` field names the slice, and `loader` shows what IDA loaded.
  272. ### `dyld_shared_cache`
  273. `open_dsc` opens one module from Apple's dyld_shared_cache. On IDA 9.4+, ida-mcp
  274. reads the DSC header directly and loads images through IDA's native `dscu`
  275. service. Older IDA builds fall back to the legacy `idat` background flow when a
  276. `.i64` has to be generated.
  277. ```
  278. # Open a module from the DSC
  279. open_dsc(path: "/path/to/dyld_shared_cache_arm64e", arch: "arm64e",
  280. module: "/usr/lib/libobjc.A.dylib")
  281. # If open_dsc returns a task_id, poll until done
  282. task_status(task_id: "dsc-<random>") # ID from the open_dsc response
  283. # Load additional frameworks for cross-module references
  284. open_dsc(path: "/path/to/dyld_shared_cache_arm64e", arch: "arm64e",
  285. module: "/usr/lib/libobjc.A.dylib",
  286. frameworks: ["/System/Library/Frameworks/Foundation.framework/Foundation"])
  287. # Incrementally load another DSC dylib into an already-open database
  288. dsc_add_dylib(module: "/usr/lib/libSystem.B.dylib")
  289. # Incrementally load a DSC data/GOT/stub region by address
  290. dsc_add_region(address: "0x180116000")
  291. # After dsc_add_dylib/dsc_add_region, confirm analysis readiness
  292. analysis_status()
  293. ```
  294. Requirements:
  295. - IDA 9.4+ for native `dscu` loading
  296. - For older IDA builds, `idat` must be available via `$IDADIR` or standard install paths
  297. ## IDAPython scripting
  298. `run_script` runs Python in the open database through IDA's IDAPython engine
  299. and returns what the script wrote to stdout and stderr. A trailing expression
  300. is returned as `result`, so a script can compute, filter, and hand back only
  301. what matters:
  302. - `result` is strict JSON of at most 1 MiB. A larger result fails the call
  303. rather than being truncated; return a smaller value or print a summary.
  304. - A value that is not JSON-serializable (custom objects, `NaN`/`Infinity`,
  305. circular references) is returned as the string of its `repr()` with
  306. `result_is_repr: true`. So is any value containing an integer outside
  307. −2⁶³ … 2⁶⁴−1, which the server's JSON reader cannot hold exactly.
  308. Imports, variables, and functions persist between calls on the same open
  309. database.
  310. ```
  311. # Inline script
  312. run_script(code: "import idautils\nfor f in idautils.Functions():\n print(hex(f))")
  313. # Run a .py file from disk
  314. run_script(file: "/path/to/analysis_script.py")
  315. # Build state in one call, return a value from the next
  316. run_script(code: "import idautils\nfuncs = list(idautils.Functions())")
  317. run_script(code: "{'count': len(funcs), 'first': hex(funcs[0]) if funcs else None}")
  318. # With timeout (default 120s, max 600s)
  319. run_script(code: "import ida_bytes; print(ida_bytes.get_bytes(0x1000, 16).hex())",
  320. timeout_secs: 30)
  321. ```
  322. All `ida_*` modules, `idc`, and `idautils` are available. See the [IDAPython API reference](https://python.docs.hex-rays.com).
  323. ## Structured results
  324. `analysis_status`, `list_functions`, `resolve_function`, `function_at`,
  325. `xrefs_to`, `xrefs_from`, `strings`, `list_lvars`, and
  326. `list_pseudocode_comments` advertise an `outputSchema` and return
  327. `structuredContent` alongside the same JSON as text. `rename_lvar`,
  328. `set_lvar_type`, and `set_pseudocode_comment` also return structured results
  329. but omit their output schemas to keep the tool inventory smaller. Other tools
  330. return JSON text only; tools whose result is a bare array or a per-call shape
  331. have no schema yet.
  332. ## Saving and crash handling
  333. `save_idb` writes the open database to disk without closing it and returns
  334. the database path it wrote. Use it to checkpoint renames, comments, types, and
  335. patches; `close_idb` also saves. If the client exits without closing, the
  336. server attempts a graceful shutdown on stdin EOF and on SIGTERM, SIGINT,
  337. SIGQUIT, or SIGHUP, which closes and packs the open database; the log names
  338. the signal. Default stdio and HTTP allow up to 120 seconds for the active
  339. operation to settle and the database to save before retiring the child. A SIGKILL
  340. skips graceful shutdown, and a caught
  341. SDK crash deliberately discards unsaved changes, so `save_idb` remains the
  342. only guarantee for edits. Finished auto-analysis is flushed to the database
  343. as soon as a raw open or `analyze_funcs` completes, because some MCP clients
  344. (Claude Code among them) end servers with SIGKILL when the conversation ends;
  345. after such a kill the analysis is on disk and only later edits are lost.
  346. Stdio JSON-RPC messages are limited to 16 MiB. An oversized request receives a
  347. correlated error when its ID is recoverable from the bounded prefix. Otherwise
  348. the server logs and discards the frame, leaving the connection open. The same
  349. applies when the ID leaves no room for a bounded response. Oversized replies
  350. return an error warning that the operation may already have changed the database.
  351. If a call crashes inside the IDA SDK (SIGSEGV/SIGBUS), ida-mcp returns an error
  352. for that call (a top-level error even from batch tools that normally report
  353. per-item failures) and then stops using that database state: the database is closed
  354. without saving, so changes since the last `save_idb` are lost, and the child
  355. worker is replaced (stdio, HTTP, and `--workspace`). Call
  356. `open_idb` again to continue.
  357. The default stdio and HTTP servers run IDA in one supervised child process (the same
  358. binary in `worker` mode), as pooled HTTP (`--max-workers N`) and `--workspace`
  359. do. A call that overruns its `timeout_secs` (or the 1800 s operation watchdog,
  360. `--workspace-worker-op-timeout-secs` for stdio, `--worker-op-timeout-secs` for
  361. HTTP) kills that child and returns a timeout:
  362. the database is then no longer open, changes since the last `save_idb` are
  363. lost, and the next `open_idb` gets a fresh worker. If its replacement is still
  364. starting, that open waits for startup, bounded to 30 seconds. This is what makes a
  365. native IDA call that never returns recoverable; nothing can interrupt it in
  366. place. On shared HTTP, cancelling a request or disconnecting stops that
  367. client's wait; an already dispatched call continues under its watchdog so
  368. other clients keep their database and unsaved edits.
  369. ### Removed tools
  370. | Removed | Use instead |
  371. |---|---|
  372. | `list_funcs` | `list_functions` (same parameters) |
  373. | `get_u8`, `get_u16`, `get_u32`, `get_u64` | `read_int` with `size` 1, 2, 4, or 8 |
  374. | `int_convert` | no replacement; do the conversion client-side or in `run_script` |
  375. Update `--tools` / `--exclude-tools` lists that name the removed tools; an
  376. unknown name is rejected at startup.
  377. ## Multiple databases and HTTP
  378. ### Workspace mode (opt-in)
  379. By default ida-mcp works on one implicit database, so tool calls don't carry a
  380. handle. To keep several databases open at once, start with `--workspace`:
  381. ```bash
  382. ida-mcp --workspace --workspace-max-workers 4
  383. ida-mcp --workspace serve-http --bind 127.0.0.1:8765 --stateless
  384. ```
  385. In workspace mode, each `open_idb`/`open_dsc` returns a `database_id`, and every
  386. database-scoped call must send it. Runtime tools such as `tool_catalog` reject
  387. it. `close_idb(database_id: ...)` closes only that handle. Idle handles are
  388. reaped after 30 minutes; `--workspace-idle-timeout-secs 0` turns that off.
  389. `list_databases` returns every routed `database_id` with its database path and
  390. state (`open`, `busy`, or `no_worker`). An agent that lost a response, or
  391. reconnected over stateless HTTP, can use it to find an open database again
  392. instead of leaving it stranded until the idle timeout. It is read-only and only
  393. appears when the server runs with `--workspace`.
  394. ### HTTP/SSE worker pool
  395. `serve-http` shares one supervised IDA child by default. To serve several
  396. stateful HTTP/SSE clients at once, set `--max-workers` above `1`. Each session
  397. then gets its own child `ida-mcp worker` process:
  398. ```bash
  399. ida-mcp serve-http --bind 127.0.0.1:8765 --max-workers 4 --min-workers 1
  400. ```
  401. Without `--max-workers N`, all HTTP sessions share one IDA context. A second
  402. client that opens another binary waits behind the first, then gets the usual
  403. `A database is already open` error. Pooled startup logs include
  404. `Starting pooled HTTP router` and `MCP pooled HTTP server listening`.
  405. An HTTP session holds its worker from the first open until `close_idb`, HTTP
  406. `DELETE`, session timeout, or server shutdown. `close_idb` releases the worker
  407. right away, but the child process may stay alive for reuse until
  408. `--worker-idle-timeout-secs` passes. When every worker is taken, new
  409. `open_idb`/`open_dsc` calls fail with `Worker pool exhausted` so clients can
  410. retry later. Pooled mode needs stateful HTTP sessions, so `--max-workers > 1`
  411. is rejected together with `--stateless`.
  412. If an SSE client exits without sending `close_idb` or HTTP `DELETE`, pooled
  413. mode closes its session once the standalone SSE stream disconnects and the
  414. `--worker-disconnect-grace-secs` reconnect window runs out. POST-only clients
  415. don't always leave a stream to watch, so their abandoned sessions are reclaimed
  416. by `--session-keep-alive-secs` (default 1800 seconds). Lower it if you need
  417. pooled workers back sooner.
  418. ### MCP 2026-07-28
  419. MCP `2026-07-28` uses the sessionless `server/discover` lifecycle. ida-mcp
  420. supports it over stdio and in the default single-worker HTTP mode, including
  421. multi-round elicitation and the `io.modelcontextprotocol/tasks` extension for
  422. background `open_dsc` calls.
  423. Pooled HTTP (`--max-workers > 1`) advertises protocol versions only up to
  424. `2025-11-25`. Its workers are tied to sessions, and MCP 2026 has no session ID
  425. to route on, so a request could reach a different IDA worker. MCP 2026 requests
  426. to pooled HTTP fail with an unsupported protocol-version error instead.
  427. ## Headless debugger (experimental)
  428. Debugger tools are off by default. On supported platforms (Apple Silicon macOS
  429. for now), start with `--enable-debugger` or `IDA_MCP_ENABLE_DEBUGGER=true` to add
  430. `debug_status`, `debug_launch`, `debug_attach`, `debug_modules`, and
  431. `debug_stop`. `debug_open_module` also needs `--workspace`, because it opens the
  432. runtime image in a new database and leaves the database that owns the live
  433. debug session alone:
  434. ```text
  435. debug_status()
  436. debug_launch(database_id: "…", path: "/absolute/path/to/program")
  437. debug_modules(database_id: "…")
  438. debug_open_module(
  439. database_id: "…",
  440. module: "/usr/lib/libobjc.A.dylib",
  441. idb_out: "~/ida-work/libobjc.i64"
  442. )
  443. debug_stop(database_id: "…", action: "auto")
  444. ```
  445. `debug_open_module` opens standalone binaries and dlopen'd plugins directly. On
  446. macOS it also resolves system libraries such as `/usr/lib/libobjc.A.dylib`
  447. through the host dyld shared cache for the target's architecture, then loads the
  448. image with the native DSC service available in IDA 9.4 and later. It doesn't extract a temporary
  449. dylib or run `idat`.
  450. `debug_open_module` always requires `idb_out`. Runtime modules often live in
  451. read-only system directories, and ida-mcp won't silently write an IDB next to
  452. them. The response includes a checked runtime slide; the new database stays at
  453. its on-disk preferred addresses.
  454. In workspace mode, a launched or attached debug session pins its database so
  455. the idle timeout skips it, until `debug_stop` succeeds or `close_idb` releases
  456. the database.
  457. Known limitations:
  458. - **A target that exits on its own keeps its pin.** IDA caches the process
  459. state and refreshes it only when a call drains the pending debug event, so
  460. ida-mcp can't see a debuggee die in the background. The database stays
  461. pinned, and exempt from the idle timeout, until `debug_stop`, `close_idb`, or
  462. worker loss clears it. Both `debug_stop` and `close_idb` handle an
  463. already-exited target correctly.
  464. - **Losing the worker doesn't stop the debuggee.** If the worker hosting a live
  465. session is killed, crashes, or is retired by ida-mcp after a wedged debugger
  466. call, it may never run its own teardown. IDA's debug-server helper can then be
  467. reparented instead of terminated, and the target may keep running. When an
  468. in-flight call detects or causes the retirement, ida-mcp returns a
  469. `Debugger session lost` error that says the target may still be alive, and
  470. clears the handle's debug pin. It never claims the debuggee ended. A leased
  471. worker can also die with no request in flight to carry an error;
  472. `list_databases` may briefly show `no_worker` before the reaper removes that
  473. handle, even with idle eviction disabled. Cleaning up a stray helper or
  474. debuggee is manual for now.
  475. ida-mcp picks IDA's signed loopback helper from the opened database's target
  476. architecture: `mac_server_arm` for ARM64 and `mac_server` for x86/x86_64. macOS
  477. may require IDA's "Take Control" authorization once per login; until it's
  478. granted, tools report `user_action_required`. ida-mcp does not ask for root,
  479. disable SIP, edit `authorizationdb`, or re-sign binaries.
  480. Linux and Windows don't advertise the debugger tools at all. IDA's ARM Linux
  481. debugger only works remotely, and ida-mcp doesn't expose remote configuration.
  482. The SDK has no Windows-on-ARM user-mode debugger. The native ARM64 test
  483. harnesses on both platforms check that the tools stay unavailable. x86 Linux
  484. and Windows stay off until a local debugger run passes on them.
  485. ## Lumina
  486. ida-mcp turns off IDA's automatic Lumina lookup by default, so starting the
  487. server or opening a database doesn't contact `lumina.hex-rays.com`. The setting
  488. lives only in ida-mcp's private IDA user profile; your normal IDA GUI profile is
  489. untouched. IDA on Windows keeps its settings in the registry rather than under
  490. `IDAUSR`, so there ida-mcp also uses a process-local registry mapping. If
  491. ida-mcp can't set up the private profile, it refuses to start.
  492. To let IDA use its configured Lumina servers, opt in for that process:
  493. ```bash
  494. ida-mcp --allow-lumina
  495. ```
  496. The environment variable equivalent is `IDA_MCP_ALLOW_LUMINA=true`.
  497. Two tools use it. Both are listed by default, but until you opt in they fail with
  498. an error telling you to restart with `--allow-lumina`:
  499. - `lumina_lookup` queries one function and reports the available metadata
  500. without changing the database.
  501. - `lumina_apply` pulls and applies metadata using IDA's upgrade policy.
  502. `force: true` may replace existing names, types, or comments.
  503. `--read-only` removes `lumina_apply` but keeps `lumina_lookup`, since a lookup
  504. doesn't modify the database.
  505. ## Context optimization
  506. By default `tools/list` returns 76 tools. In 9.5.0, its compact tool array is
  507. about 62.2 KB of JSON, or roughly 15.5k tokens using the `measure-tools` estimate.
  508. Six debugger tools are gated by `--enable-debugger` on supported hosts;
  509. `debug_open_module` also needs `--workspace`. The seventh opt-in tool,
  510. `list_databases`, appears in workspace mode. Clients with dynamic tool discovery defer
  511. the schema cost; clients that preload schemas pay it every session. To trim the
  512. surface to what you need:
  513. | Flag | Env var | Effect |
  514. |---|---|---|
  515. | `--profile=lean` | `IDA_MCP_PROFILE` | Starts from the 28-tool `lean` set (below) instead of all tools |
  516. | `--toolsets=cat1,cat2` | `IDA_MCP_TOOLSETS` | Replaces "all tools" with the union of selected categories |
  517. | `--tools=t1,t2` | `IDA_MCP_TOOLS` | Adds individual tools (additive to `--toolsets`) |
  518. | `--exclude-tools=t1,t2`| `IDA_MCP_EXCLUDE_TOOLS` | Subtracts from the include set; always wins |
  519. | `--read-only` | `IDA_MCP_READ_ONLY` | Strips mutating/arbitrary-code tools (`run_script`, `save_idb`, `patch*`, `rename`, comment setters, `lumina_apply`, type/stack edits, `dsc_add_*`, `analyze_funcs`, and debugger process control); keeps lifecycle/discovery |
  520. With no flags you get all 76 baseline tools. Categories: `core`, `functions`,
  521. `disassembly`, `decompile`, `xrefs`, `control_flow`, `memory`, `search`,
  522. `metadata`, `types`, `editing`, `scripting`; `debug` exists only when the
  523. debugger is enabled on a supported platform (run `tool_catalog` to list them).
  524. Flags override env vars, and unknown names are rejected at startup.
  525. `--read-only` filters the exposed MCP tools. Database lifecycle calls remain
  526. available and can create or save IDB files; it is not a filesystem sandbox.
  527. ### The `lean` profile
  528. `--profile=lean` advertises 28 tools, about 26.3 KB of `tools/list` JSON, chosen for Apple
  529. reverse engineering: opening binaries, caches and debug info
  530. (`open_idb`, `open_dsc`, `dsc_add_dylib`, `dsc_add_region`, `load_debug_info`,
  531. `analysis_status`, `analyze_funcs`, `save_idb`, `close_idb`, `task_status`),
  532. reading code and references (`list_functions`, `resolve_function`,
  533. `function_at`, `disasm`, `decompile`, `xrefs_to`, `xrefs_from`, `callers`,
  534. `callees`, `strings`, `find_bytes`, `search`, `segments`, `imports`,
  535. `exports`), annotating (`rename`, `set_comments`), and `run_script` for
  536. everything else. `tool_catalog`/`tool_help` are left out because the schemas
  537. are already advertised; the server instructions adapt to whatever is enabled.
  538. The profile composes with the other flags: `--tools` adds to it,
  539. `--exclude-tools` and `--read-only` subtract (`--profile=lean --read-only` is
  540. 21 tools, 21.9 KB). The default stays the full set for compatibility; the
  541. profile is the measured recommendation for Claude Code (below).
  542. ```bash
  543. ida-mcp --profile=lean
  544. ```
  545. Measured with `bench/` (Claude Code 2.1.288, Sonnet 5.5, medium effort,
  546. three trials per cell, 2026-10-03) on an annotate / string-xrefs / universal
  547. Mach-O task mix: both profiles completed all nine conversations correctly.
  548. Lean cost 25% less than full ($0.275 vs $0.367), used 42 vs 52 tool calls,
  549. and recorded 0 vs 1 MCP tool errors; cache-read input fell from 849,325 to
  550. 442,166 tokens. The saving is almost all cache-read tokens from the smaller
  551. inventory, so it applies to clients that send the tool list with every
  552. request. No other client was measured. See [the benchmark harness](bench/README.md)
  553. for the tasks, correctness oracles, and reproduction instructions.
  554. ### Recommendations by client
  555. - **Claude Code:** use `--profile=lean` for the Apple RE workflows covered by the benchmark. Add `--tools` for anything you need beyond it.
  556. - **Clients that load every schema into context:** choose a focused subset to reduce the advertised tool list:
  557. ```bash
  558. ida-mcp --toolsets=core,functions,disassembly,decompile,xrefs
  559. ```
  560. - **Clients with deferred tool discovery:** the full default is useful for broad work. Filters still let you constrain the operations available to the agent. A read-only disassembly setup is:
  561. ```bash
  562. ida-mcp --toolsets=core,functions,disassembly,decompile --read-only
  563. ```
  564. - **Small / local models:** use the smallest surface that works. For triage:
  565. ```bash
  566. ida-mcp --toolsets=core,functions --tools=decompile,callees,callers --read-only
  567. ```
  568. ### Configuring through `mcpServers.json`
  569. Most MCP configs run `ida-mcp` with no subcommand. The env vars work there too:
  570. ```json
  571. {
  572. "mcpServers": {
  573. "ida-mcp": {
  574. "command": "ida-mcp",
  575. "env": {
  576. "IDA_MCP_TOOLSETS": "core,functions,disassembly,decompile,xrefs",
  577. "IDA_MCP_READ_ONLY": "true"
  578. }
  579. }
  580. }
  581. }
  582. ```
  583. ### Measuring
  584. `just measure-tools` prints a per-tool character count and a rough token estimate.
  585. It measures the full default list unless filter environment variables are set.
  586. For example, `env IDA_MCP_PROFILE=lean just measure-tools` measures the lean
  587. profile. For the client's actual token usage, use its context view (`/context`
  588. in Claude Code, or the equivalent elsewhere).
  589. ## Docs
  590. - [docs/TOOLS.md](docs/TOOLS.md) - Tool catalog and discovery workflow
  591. - [docs/TRANSPORTS.md](docs/TRANSPORTS.md) - Stdio vs Streamable HTTP
  592. - [docs/BUILDING.md](docs/BUILDING.md) - Build from source
  593. - [docs/TESTING.md](docs/TESTING.md) - Running tests
  594. ## License
  595. MIT Copyright (c) 2026 **blacktop**

Ratings and comments

Sign in to rate this skill.

Sign in

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