Hex-Rays IDA MCP

⚠️ Experimental prerelease ⚠️

Official Hex-Rays IDA MCP Server.

Installation

Requirements

• Installed in your PATH
  • Git
  • uv
• IDA 9.4 or higher with idalib and Python 3.11+
• Other IDA MCP servers must be disabled to reduce agent confusion

IDA GUI Plugin

To support IDA GUI instances when using Hex-Rays IDA MCP, install the plugin:

uvx ida-hcli plugin install https://github.com/HexRaysSA/ida-mcp
# or if you have hcli installed:
hcli plugin install https://github.com/HexRaysSA/ida-mcp

Note: Without the GUI plugin, IDA MCP will only work headlessly.

Claude Code

# Add Hex-Rays marketplace
claude plugin marketplace add HexRaysSA/claude-marketplace
# Install plugin
claude plugin install ida-mcp@HexRaysSA
# Update to latest version
claude plugin update ida-mcp@HexRaysSA

Codex CLI

# Add Hex-Rays marketplace
codex plugin marketplace add HexRaysSA/codex-marketplace
# Install plugin
codex plugin add ida-mcp@HexRaysSA

GitHub Copilot CLI

# Add Hex-Rays marketplace
copilot plugin marketplace add HexRaysSA/copilot-marketplace
# Install plugin
copilot plugin install ida-mcp@HexRaysSA
# Update to latest version
copilot plugin update ida-mcp

Pi

# Install extension
pi install git:github.com/HexRaysSA/ida-mcp@latest
# Update to latest version
pi update --extensions

oh-my-pi

# Install extension
omp plugin install github:HexRaysSA/ida-mcp#latest
# Update to latest version
omp plugin upgrade

Other agents

Configure a regular stdio MCP server in your MCP JSON configuration:

{
  "mcpServers": {
    "ida": {
      "command": "uvx",
      "args": [
        "--exclude-newer=1s",
        "ida-mcp",
        "stdio",
        "--agent=my-agent"
      ]
    }
  }
}

uvx resolves the latest stable ida-mcp release from PyPI, so this configuration does not need to be updated for each release.

--agent=my-agent is a human-chosen label (like claude-code, cursor, my-custom-agent, etc.) used to differentiate sessions in the dashboard.

Commands

Every invocation requires a subcommand:

# MCP server over standard input/output
uvx ida-mcp stdio --agent=my-agent

# MCP server over Streamable HTTP
uvx ida-mcp http --host 127.0.0.1 --port 8737

# Inspect semantic MCP sessions
uvx ida-mcp dashboard --open

# Export sessions, linked agent transcripts, and Nexus worker logs
uvx ida-mcp logs

# Agent integrations use these as pre-tool hooks
uvx ida-mcp hook claude
uvx ida-mcp hook codex
uvx ida-mcp hook copilot

Semantic session files remain in the shared IDA Nexus state directory under sessions/, including when IDA_NEXUS_STATE_DIR overrides that directory.

Embedding

The server API is available from ida_mcp.mcp for applications that need to add tools or host Streamable HTTP themselves:

from ida_mcp.mcp import serve_http, stop_http_server, tool


@tool
def application_status() -> str:
    """Return the embedding application's status."""
    return "ready"


serve_http("127.0.0.1", 8737, path_prefix="/hex-rays")
# Later, during application shutdown:
stop_http_server()

serve_http() also accepts a DatabaseManager subclass and constructor arguments for hosts that provide custom database resolution. See the architecture documentation for lifecycle, tracing, and archive details.

We tested the following clients, but any MCP client should work similarly:

• Antigravity
• LM Studio

Example Usage

Start your agent harness and ask it something like:

Reverse /path/to/sample.elf for me

To test the GUI integration, open something in IDA and ask your harness:

What do I have open in the IDA GUI?

Developers: IDA Nexus

The IDA MCP project is built on IDA Nexus, which allows multiple clients to seamlessly share and operate on IDA databases.

You can build your own tools on top of the ida-nexus library, see the documentation for more information.