IDA Pro MCP

IDA Pro MCP is a local Model Context Protocol server for IDA Pro. It lets an MCP client inspect an IDB, ask IDA for deterministic analysis results, and, when explicitly allowed, write annotations or other changes back to the IDB. The host process runs outside IDA and starts a separate IDA headless process for each session by default.

Why this implementation

• Deterministic agent surface: 109 strict-schema ida_* operations with live discovery through tools/list and ida_help.

• Local-first architecture: the host and IDA runtime communicate over a token-protected loopback bridge; no hidden LLM service sits in the analysis path.

• Evidence, not just chat: durable findings preserve provenance, confidence, lifecycle state, conflicts, and audit history outside the IDB.

• Guarded mutations: IDB-changing operations remain behind explicit policy and risk-acknowledgement controls.

• Broad client support: the installer understands more than 22 agent environments and their JSON, JSON5, TOML, and YAML configuration shapes.

The current version is 1.0.0a3. This is alpha software. The public ida_* operation names, schemas, and workspace format may change before a stable 1.0.0 release. The default client surface contains 109 exact-schema operations. Use live discovery for the complete contract: tools/list enumerates every operation with its schema, and ida_help(topic="...") returns the exact arguments and example for one operation.

Related MCP server: ida-domain-mcp

Before you install

You need:

• IDA Pro or IDA Home 9.2 or newer, with a usable idat/idat64 executable. The repository’s live test evidence covers IDA 9.3 and 9.4; 9.2 is the declared compatibility floor.

• Python 3.11 or newer for the host and installer.

• Permission to run IDA on the binaries you plan to inspect, and enough disk space for a managed Python environment, session files, and IDB copies.

• An MCP client that supports a local stdio server, such as Claude Code, Codex, OpenCode, Claude Desktop, Cursor, VS Code/Copilot, Windsurf, Cline, Roo Code, Gemini CLI, or Antigravity.

Normal analysis does not require a language model or an embedding model. The optional semantic-search features use a local model by default and remain disabled when no model is configured.

The default runtime is idat: one headless IDA process per session. The idalib backend is experimental, requires an IDA 9.3-or-newer installation with the idapro package activated, and is not needed for a first install.

Install from the source checkout

The installer creates a managed environment under the install root, installs a frozen copy of the checkout into it, and writes client configuration for the supported client locations. From the repository root, run:

python3 install.py

For a known IDA installation, pass it explicitly:

python3 install.py --ida-dir /path/to/ida-pro-9.3

For a non-interactive run:

python3 install.py --yes --no-ida-prompt --ida-dir /path/to/ida-pro-9.3

The installer can also find IDA through IDADIR, IDA_DIR, the IDA executables on PATH, and common installation directories. --ida-version selects a version when more than one installation is present. Use --dry-run to inspect the planned changes first.

The installer does not download an embedding model unless you select or request one. It may create or update configuration files for every client location in its built-in client map, including clients that are not installed on your machine. Check install-report.json in the install root and remove unused entries if necessary. Existing regular configuration files are backed up before they are changed; malformed, symlinked, or non-regular files are refused rather than overwritten.

Restart the MCP client after installation so it reloads its configuration.

Agent harnesses discover the tool surface live: tools/list enumerates every operation with its schema, and ida_help(topic="...") returns exact arguments and an example. No static skill files are installed.

The default install root is:

• Linux and macOS: ~/.local/share/ida-pro-mcp

• Windows: %LOCALAPPDATA%/ida-pro-mcp

Set IDA_PRO_MCP_HOME or pass --install-root to choose another location.

Install from a release artifact

Alpha releases are built by GitHub Actions and published manually as prereleases. When a release is available, download the bundle.zip or bundle.tar.gz asset and its SHA256SUMS file from the releases page. Verify the checksum, extract the bundle, and run the installer from its top-level directory:

python3 install.py --yes --no-ida-prompt --ida-dir /path/to/ida-pro-9.3

The release also contains a wheel and source distribution for scripted Python installations. The bundle is the simplest route because it includes the installer and all project files needed to configure an MCP client. Releases are alpha quality; keep the original binary and IDB and read the release notes before upgrading.

Connect an MCP client

The installer writes the server entry for the client configuration paths it knows. It supports Gemini CLI, Antigravity, Antigravity IDE, Antigravity CLI, Claude Code, Codex, Copilot CLI, OpenCode, Claude Desktop, Cursor, VS Code, Windsurf, Cline, and Roo Code. OpenCode and Copilot-family clients use different configuration shapes; let the installer write those files or follow the OpenCode setup guide.

For a client that uses the common JSON format, the entry is equivalent to:

{
  "mcpServers": {
    "ida-pro-mcp": {
      "command": "/path/to/ida-pro-mcp/.venv/bin/python",
      "args": ["-u", "-m", "ida_pro_mcp.host.server"],
      "env": {
        "IDA_PRO_MCP_HOME": "/path/to/ida-pro-mcp",
        "IDADIR": "/path/to/ida-pro-9.3",
        "IDA_MCP_TOOL_SURFACE": "agent"
      }
    }
  }
}

On Windows, use the managed interpreter at <install-root>/.venv/Scripts/python.exe. The important details are the managed interpreter, -u -m ida_pro_mcp.host.server, the selected IDA directory, and IDA_MCP_TOOL_SURFACE=agent. Do not point the client at install.py; that file is the installer, not the MCP server.

After changing a client configuration, fully restart the client and check that ida_help appears in its available operations. If the client shows only a legacy broad tool(action=...) interface, check that the environment selects the default agent surface rather than IDA_MCP_TOOL_SURFACE=legacy.

A first useful session

Use an absolute path to a test binary first. Opening a binary normally waits for IDA’s initial analysis to finish; a large binary can take time.

ida_open_binary(binary_path="/absolute/path/to/sample")
ida_session_status()
ida_overview()
ida_list_imports(limit=30)
ida_list_strings(query="http", limit=30)
ida_find(query="main", limit=20)
ida_decompile(address="<address returned by IDA>")
ida_xrefs_to(address="<same address>")

Use ida_help(topic="ida_decompile") whenever you need the exact argument schema. Public operation schemas are strict: unknown arguments are rejected. Addresses may be accepted as integers or strings according to the individual operation contract; use the form shown by ida_help for the operation in your client.

For a small investigation record, the workspace findings operations are:

ida_write_finding(title="Input reaches parser", address="<address returned by IDA>", kind="finding", status="confirmed", confidence=0.8, evidence=[{"type":"call", "value":"recv", "address":"<evidence address>"}])
ida_analysis_brief()
ida_next_target()
ida_export_findings(format="markdown")

Workspace findings are kept separately from IDB edits. If the active policy permits the workspace write, ida_write_finding records a finding locally; otherwise the server returns a policy error. ida_publish_findings(dry_run=true) previews IDB changes. Publishing, renaming, patching, and other IDB mutations are policy-gated and require the operation’s documented acknowledgement where the operation exposes one.

Operations at a glance

The front page stays task-oriented, but this compact index keeps the public surface easy to scan. Each name below is prefixed with ida_ when called. The complete schemas and examples are available live via tools/list and ida_help(topic="...").

What is safe, and what is not

The server’s baseline policy is assist. A session may tighten the operator’s baseline policy but cannot relax it. The policy is deterministic; it does not decide that a risky operation is safe because a client asks for it.

Read-only inspection is the normal starting point. Examples include ida_overview, ida_find, ida_list_functions, ida_list_strings, ida_list_imports, ida_decompile, ida_disassemble, ida_xrefs_to, ida_callers, ida_callees, ida_callgraph, ida_read_bytes, and the calculation operations. These still consume local files and IDA resources, and the MCP client receives their results.

The following actions change durable state or execute code and should be treated as high impact:

• ida_rename, ida_comment, ida_patch_bytes, function/type/segment/data changes, signature application, ida_save_idb, snapshots, and undo/restore operations can change the IDB or related state.

• ida_publish_findings writes findings into the IDB. Run its dry-run form first; the non-dry-run form is gated.

• ida_close_session tears down the live IDA runtime and is destructive from the session’s point of view.

• ida_python executes arbitrary Python in the active IDA process. It is blocked in safe mode and requires an explicit risk acknowledgement under the normal policy.

• ida_emulate is useful for controlled checks, but mutating emulator actions require the corresponding acknowledgement.

• ida_til_export and ida_til_import access the filesystem and are gated. Filesystem paths are constrained by the configured memory root where that guard applies.

Do not use --disable-policy as a convenience flag. It sets IDA_MCP_POLICY_MODE=off and disables all policy gates, including write acknowledgements and other workflow controls. If a call is denied, read the operation’s ida_help entry and supply the exact acknowledged argument only when that operation’s schema supports it.

While IDA is still performing initial analysis, safe mode blocks some full-binary analysis, indexing, and script operations. It is intended to keep early-session calls narrow; poll ida_session_status or ida_session_health rather than bypassing the guard.

The bridge listens on loopback and uses a per-session token. It is not a network service: do not expose or forward the bridge port to an untrusted network. Treat imported scripts, traces, binaries, corpus data, and client requests as untrusted input.

Privacy and data handling

The normal host-to-IDA path is local. The project does not run a built-in LLM service in the analysis path, and local embedding is opt-in. That does not make the whole workflow automatically offline:

• The connected MCP client receives paths, symbols, strings, bytes, decompilation, findings, and other results. The client or its model provider may transmit that context according to its own account, model, and retention settings. IDA Pro MCP cannot control those transfers.

• If you explicitly select the Gemini embedding backend, the server sends a compact behavioral signature to Google rather than a full decompilation. The signature can still contain code-derived calls, constants, string literals, and control-flow information. Do not enable it for binaries that must remain on the workstation.

• Installer dependency downloads, optional model and llama-server downloads, optional threat-corpus downloads, and external Rizin/radare2 integrations can make network requests when enabled.

• Local cache, logs, session metadata, managed IDBs, and the blackboard may contain paths, analysis metadata, and findings. Protect the install/data directories. If you pass a Gemini AI Studio key to the installer, the key may be written into the generated MCP client environment block; prefer an environment-based credential and review the client configuration.

For a local-only setup, use the default local runtime, leave Gemini and other optional downloads disabled, and configure the MCP client and its model according to your organization’s data policy. “Local-only” still requires checking what the client sends to its own model provider.

Common troubleshooting

The installer cannot find IDA

Pass the installation directory explicitly:

python3 install.py --ida-dir /path/to/ida-pro-9.3

You can also set IDADIR or IDA_DIR. If several installations are found, use --ida-version 9.3 or --no-ida-prompt to control selection. Confirm that the selected directory contains a runnable idat or idat64.

The client does not show IDA Pro MCP

Restart the client and inspect its configuration entry. Confirm that its command uses the managed venv Python and -u -m ida_pro_mcp.host.server, and that the env block contains the correct IDADIR. Review install-report.json; the installer records client update failures and keeps backups next to modified files. OpenCode and Copilot-family configuration shapes differ from the common JSON example.

Opening a binary takes a long time or appears stuck

The normal ida_open_binary call waits for initial analysis. Check ida_session_status and ida_session_health, allow more time for a large binary, and check the per-session logs under the install/data directory. The background-open operation is available, but it is intended for cases where you understand its asynchronous behavior and safe-mode restrictions.

A write operation is denied

This is usually the policy working as configured. Use ida_help to inspect the operation’s exact schema and its acknowledgement requirement. Do not add arbitrary arguments: schemas are strict. Review IDA_MCP_POLICY_MODE and the operator policy file before changing policy. Disabling all policy gates is a separate, deliberately unsafe choice.

Semantic search is unavailable

Semantic search is optional and requires an index and a compatible embedding backend. Ordinary listing, search, decompilation, and cross-reference work do not require it. To set up the optional local path, use the installer’s explicit embedder options, for example:

python3 install.py --setup-embedder

The installer can also run --embedder-doctor, use an explicit model path, or download a selected model and llama-server when requested. Model licenses, disk use, and network downloads are your responsibility. If the model is missing, the server should report semantic search as unavailable rather than pretending that it ran.

The installer refuses a client configuration

Fix the reported JSON, JSONC, or TOML syntax and rerun the installer. It also refuses symlinked and non-regular configuration paths to avoid overwriting an unexpected target. Existing regular files are backed up; the installer’s default rollback behavior can restore those backups if a later phase fails.

An IDA session or runtime fails

Check ida_session_health, the session log, and the bridge log. Confirm that the client is using the same install root and IDADIR that the installer recorded. The default idat backend gives each session its own process; do not switch to experimental idalib while diagnosing a basic installation.

Reference material

• Project wiki — task-oriented installation, investigation, editing, and troubleshooting guides.

• Local wiki pages — the same hand-authored material shipped for the built-in wiki tool.

• Live operation discovery — tools/list and ida_help expose every public operation, schema, and example.

• Safety model — trust boundaries, policy modes, loopback transport, session ownership, and filesystem guards.

• Investigation workspace — findings, evidence, targets, and exports.

• Intelligence and embeddings — local and optional Gemini retrieval backends.

• OpenCode setup — OpenCode configuration.

• Architecture — host, IDA runtime, and data flow for readers who need implementation detail.

• Security policy — reporting and security guidance.

• Live IDA testing — what the repository’s tests do and do not prove about a real IDA installation.

• Versioning and release checklist and the changelog — alpha status and release history.

• Documentation index — the full map of maintained guides, references, wiki pages, and research notes.

For exact operation names, use the generated reference or ask the running server with ida_help. The older tool(action=...) backend remains available for compatibility and is selected with IDA_MCP_TOOL_SURFACE=legacy; new integrations should use the exact-schema ida_* surface.