ida-mcp-rs

Why ida-mcp

• Built for Apple targets. Universal Mach-O slice selection, dSYM/DWARF loading, and dyld_shared_cache module and dylib loading are single tool calls with explicit parameters, not scripts the agent has to write. In a measured Claude Code run, selecting and analyzing the x86_64 slice of a universal binary took one call and about five seconds.
• Fast and lean. A native Rust server driving IDA through idalib; a 28-tool --profile=lean measured 25% cheaper than the full set on real tasks with the same correctness, and the full set is there when you need it.
• Safe to leave running. Exact-target edits, save_idb checkpoints, analysis flushed to disk as soon as it finishes, graceful shutdown on every signal a client sends, and database state discarded rather than trusted after an IDA crash.
• Scriptable when the tools run out. run_script returns a trailing expression as JSON and keeps state between calls, so one script can find, filter, and return only what matters.

Prerequisites

• IDA Pro 9.4 with a valid license
• IDA Pro 9.5 beta for the beta release

Getting started

Install

macOS / Linux (via Homebrew)

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)

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

Windows note: see Windows below for DLL discovery options.

macOS / Linux (via Nix)

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

Direct download: grab the archive for your platform from GitHub Releases.

Build from source: see 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 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. There are no beta packages for Linux or Windows; build main from source as described in 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, 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")
$pathEntries = @($userPath -split ";" | Where-Object { $_ })
if (-not ($pathEntries -contains $idaDir)) {
  [Environment]::SetEnvironmentVariable(
    "Path", (@($pathEntries + $idaDir) -join ";"), "User"
  )
}
# Then restart your terminal
claude mcp add ida -- ida-mcp

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.

Common IDA paths:

• C:\Program Files\IDA Professional 9.4
• C:\Program Files\IDA Pro 9.4
• C:\Program Files\IDA Home 9.4

Runtime requirements

The binary links against IDA's libraries at runtime. Baked-in RPATHs cover the standard install paths. For anything else:

Configure your AI agent

Claude Code

claude mcp add ida -- ida-mcp

Codex CLI

codex mcp add ida -- ida-mcp

Gemini CLI

gemini mcp add ida -- ida-mcp

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "ida": { "command": "ida-mcp" }
  }
}

Usage

Once your agent is configured, it can drive the tools directly:

# Open a binary. This returns quickly; analysis runs separately.
open_idb(path: "~/samples/malware")

# Keep the generated database out of a read-only input directory
open_idb(path: "/System/example", idb_out: "~/ida-work/example.i64")

# Pick one slice of a universal (fat) Mach-O
open_idb(path: "/bin/ls", arch: "arm64e", idb_out: "~/ida-work/ls.i64")

# These work immediately, no analysis needed
list_functions(limit: 20)
disasm_by_name(name: "main", count: 20)
strings(limit: 10)

# For xrefs/decompile on large binaries, run analysis in the background
analyze_funcs(background: true)   # returns task_id
task_status(task_id: "analyze-<random>") # poll progress (ID from the analyze_funcs response)

# Decompile (requires Hex-Rays + completed analysis)
decompile(address: "0x100000f00")

# Discover more tools
tool_catalog(query: "find callers")

Tools that change the database (rename, set_comments, patch, patch_asm, apply_types, declare_stack, delete_stack, and lumina_apply) take exactly one address or one symbol name. Names must match exactly, case included. A near miss changes nothing and returns up to eight similar names with their addresses. A returned target record identifies the database, resolved symbol (or null), and requested and effective addresses. Check the operation's result to determine whether the change succeeded.

For Hex-Rays locals and arguments, use list_lvars with one function address or exact target_name. rename_lvar and set_lvar_type take the same function selector plus exactly one of lvar_locator or lvar_name. Prefer the opaque locator returned by list_lvars: display names such as v1 can move to a different local after a prototype change. A stale or ambiguous locator fails without making a change. Locals without a locator are edited by exact, unique name. The tools return the variable as it was before the edit and the resolved function target. Use save_idb to checkpoint edits to disk.

list_lvars(target_name: "interesting_function")
rename_lvar(target_name: "interesting_function", lvar_locator: "<locator from list_lvars>", new_name: "count")
set_lvar_type(target_name: "interesting_function", lvar_loc