IDA Pilot

Drive IDA Pro's decompiler and disassembler from an AI agent over the Model Context Protocol — headless, fast, and token-frugal.

Headless IDA Pro analysis server exposing MCP tools (28 with py_eval enabled, 27 without). Designed for AI agents — tiered tool loading, multi-layer caching, batch operations, and compact payloads minimize token cost per turn.

Go orchestrates sessions and caching. Python workers run IDA via idalib. Communication uses Connect RPC over TCP.

• Built for agents, not humans. Every response is compact — hex addresses, sparse fields, [address, type] xref tuples, "ok" instead of {"success": true} — to spend the fewest tokens per turn.
• One call, not ten. Composite tools like survey_binary and analyze_function return decompilation + metadata + xrefs + comments in a single round-trip; analyze_functions batches up to 10 at once.
• Stays responsive on huge binaries. Loading and auto-analysis run detached with a live progress heartbeat, so a 200 MB binary won't stall or time out your MCP client — you poll until ready=true and keep working.
• Tiered tool surface. Agents boot with 3 tools; read/analysis and write tools promote in as the workflow advances, keeping the per-turn schema small.
• Multi-binary. Open several databases and cross_reference / cross_search across them.
• Safe by default. Loopback-only bind, py_eval off, Origin/Host guard, optional path allowlist (details below).

IDA Pilot has no built-in authentication. The defaults are tuned for a single trusted MCP client on the same machine:

• Bound to 127.0.0.1 by default. Only callers on the local host can reach it. Override with --bind 0.0.0.0 (or IDA_PILOT_BIND) only if you are putting an authenticated reverse proxy in front.
• Origin / Host validation on every request when bound to loopback — blocks DNS-rebinding and browser cross-origin attacks.
• py_eval is OFF by default. It runs arbitrary Python inside the IDA worker (full host filesystem + network access). Enable explicitly with --enable-py-eval (or IDA_PILOT_ENABLE_PY_EVAL=1) and treat the resulting endpoint as an RCE primitive — anyone who can reach the port can execute code.
• Filesystem allowlist (opt-in). By default a client can open any file the server user can read (open_binary, import_metadata). Set --allowed-roots (or IDA_PILOT_ALLOWED_ROOTS) to confine those paths to specific directories — recommended whenever you expose the port. Paths are symlink-resolved before the check, so a link inside a root can't escape it.

The truncated-output cache (get_cached_output) is process-global with no per-session ACL — the server has no client identity to bind entries to — so access rests on unguessable 128-bit cache IDs plus the loopback/Origin guards above, not on session ownership.

In short: a fresh ./bin/ida-pilot run is safe to leave on; opening the port to the network or enabling py_eval is an explicit choice and your responsibility to protect.

MCP Client (Claude, Cursor, etc.)
    │
    │  Streamable HTTP / SSE
    ▼
Go Server (:17300)
    │  session registry, tool tiers, caching, output pagination
    │
    │  Connect RPC (TCP)
    ▼
Python Worker (one per binary)
    │  idalib + Hex-Rays decompiler
    ▼
IDA database (.i64)

• IDA Pro 9.0+ with idalib activated (docs)
• Go 1.25+
• Python 3.10+ (the supported floor; CI and mise pin 3.12)

git clone https://github.com/wklwkl115/ida-pilot.git
cd ida-pilot
pip install -r python/requirements.txt
go build -o bin/ida-pilot ./cmd/ida-pilot

./bin/ida-pilot --debug

The server listens on http://localhost:17300/ (Streamable HTTP) and http://localhost:17300/sse (SSE fallback).

Add to your MCP client configuration:

{
  "mcpServers": {
    "ida-pilot": {
      "type": "http",
      "url": "http://127.0.0.1:17300/"
    }
  }
}

Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)

Claude Code: .mcp.json in project root or ~/.claude/settings.json

Cursor: .cursor/mcp.json in project root

IDA Pilot is built for agents, not humans. Every design decision targets lower token cost and fewer round-trips.

Agents start with 3 tools. More appear as needed — the schema payload per turn stays small.

When the last session closes, tools demote back to Tier 0. Adding --enable-py-eval registers one more Tier-1 tool, taking the full surface to 28.

One call replaces many. These are the primary entry points for analysis:

• survey_binary — segments, function/import/export/string counts with top entries, entry point, decompiler status. One call to orient.
• analyze_function — pseudocode + metadata + xrefs + comments for a single function. All cached.
• analyze_functions — batch-analyze up to 10 functions in parallel.
• annotate_function — batch rename, retype, and comment in a single call per function.

Background cache warming starts automatically when a binary is opened — survey_binary returns instantly on its first call.

• Addresses are hex (0x...) on both input and output, so the agent pastes back exactly what it sees in disassembly/listings (decimal is also accepted on input)
• Sparse fields: zero/false/empty values omitted
• Xrefs as [address, type] tuples instead of objects
• Write operations return "ok" instead of {"success": true}
• Responses over 8KB auto-truncated with pagination via get_cached_output
• Session ID auto-detected when only one session is active

Agents lose context on long conversations. IDA Pilot tracks it server-side:

• set_analysis_note — attach notes to addresses during analysis
• get_analysis_context — retrieve all visited functions and notes to recover state

The surface is intentionally small: related operations are consolidated behind a few dispatcher tools that take a discriminator field (category, mode, action, target, format). 28 tools across three tiers.

open_binary does not block: loading and auto-analysis run in a background worker thread so the call returns at once (large binaries take minutes to analyze). Poll get_session_progress until ready=true before issuing analysis tools — they are gated and return a not ready error until then. Status RPCs stay responsive throughout because the worker serializes IDA access on a single thread while answering progress queries from cached state.

--bind              Bind interface (default 127.0.0.1; use 0.0.0.0 only behind an auth proxy)
--port              HTTP port (default: from config.json)
--config            Config file path (default: config.json)
--worker            Python worker script path
--max-sessions      Max concurrent sessions
--session-timeout   Session idle timeout (e.g. 4h)
--debug             Verbose logging
--enable-py-eval    Register the py_eval tool (arbitrary Python in the IDA worker — RCE primitive)
--allowed-roots     Restrict agent-supplied paths to these dirs (OS-path-list separated; empty = unrestricted)

IDA_PILOT_BIND=127.0.0.1
IDA_PILOT_PORT=17300
IDA_PILOT_SESSION_TIMEOUT_MIN=240
IDA_PILOT_MAX_SESSIONS=10
IDA_PILOT_WORKER=/path/to/worker.py
IDA_PILOT_DEBUG=1
IDA_PILOT_ENABLE_PY_EVAL=0
IDA_PILOT_ALLOWED_ROOTS=/srv/samples:/data/binaries   # OS-path-list separated; empty = unrestricted

{
  "bind": "127.0.0.1",
  "port": 17300,
  "session_timeout_minutes": 240,
  "max_concurrent_sessions": 4,
  "database_directory": "./databases",
  "python_worker_path": "python/worker/server.py",
  "debug": false,
  "enable_py_eval": false,
  "allowed_roots": []
}

make build          # Build server
make test           # Run tests
make proto          # Regenerate protobuf (requires protoc)
make clean          # Clean artifacts
make inspector      # Launch MCP Inspector at localhost:5173

ida-pilot/
├── cmd/ida-pilot/        # Server entry point
├── internal/
│   ├── server/           # MCP tool handlers, caching, tiers
│   ├── session/          # Session registry + persistence
│   └── worker/           # Python worker process manager
├── proto/                # Protobuf service definitions
└── python/worker/        # idalib wrapper + Connect RPC server

Contributions are welcome — see CONTRIBUTING.md for setup, the local test gates, and conventions. To report a security issue privately, see SECURITY.md.

MIT