ida-mcp

Because IDA requires main-thread access and one IDA process can only own one active database at a time, the server uses different strategies based on the --max-workers setting:

• --max-workers 1: All HTTP sessions are serialized through a single worker loop.
• --max-workers N (where N > 1): The server uses a child-process worker pool. Each opened HTTP session leases a child ida-mcp worker process. This allows different sessions to own different IDBs concurrently.

Session Lifecycle & Reclaiming:

• Manual Release: A lease is released immediately when close_idb is called or an HTTP DELETE is sent.
• SSE Clients: If an SSE client disconnects without a manual release, the session is closed after the --worker-disconnect-grace-secs elapses.
• POST-only Clients: Since they lack a persistent stream, orphaned sessions are reclaimed via the --session-keep-alive-secs timeout.

Integration tests verify the interaction between the MCP server and IDA Pro across several transport and functional layers:

Stdio Integration (just test)

Verifies the MCP protocol handshake, tool discovery (tool_catalog, tool_help), and a wide range of IDA operations including:

• Database: open_idb, close_idb, idb_meta, analysis_status.
• Analysis: list_functions, resolve_function, disasm_by_name, find_insns, find_insn_operands.
• Editing: set_comments, rename, patch, patch_asm.
• Types/Stack: declare_type, apply_types, infer_types, stack_frame, declare_stack, delete_stack.
• Metadata: segments, strings, imports, exports, structs, xrefs_to_field, search_structs.

HTTP/SSE Integration (just test-http)

Verifies streamable HTTP transport using Server-Sent Events (SSE). It ensures tools/list returns the full toolset and that database operations (like open_idb and list_functions) function correctly over the HTTP transport.

Scripting Integration (just test-script)

Verifies the run_script tool, which allows running inline Python or executing .py files. It checks for correct stdout/stderr capture and Python error reporting.

Elicitation and Background Analysis (just test-elicitation)

Tests how the server handles clients with different capabilities:

• Non-elicitation clients: Verifies that open_idb(auto_analyse=true) silently routes analysis to a background task.
• Elicitation-capable clients: Verifies the client receives elicitation/create, accepts it, and receives analysis_background=true along with a pollable analysis_task_id.

Once configured, you can interact with binaries using the following toolset via your AI agent:

Basic Operations

• open_idb(path: "..."): Opens a binary. Returns quickly; analysis runs in the background.
• list_functions(limit: int): Lists functions.
• disasm_by_name(name: "...", count: int): Disassembles by function name.
• strings(limit: int): Lists strings.

Advanced Analysis

• analyze_funcs(background: true): Runs analysis in the background. Returns a task_id.
• task_status(task_id: "..."): Polls the progress of a background task.
• decompile(address: "..."): Decompiles a specific address (requires Hex-Rays and completed analysis).
• tool_catalog(query: "..."): Discovers available tools.

IDAPython Scripting

Execute arbitrary Python code via IDA's engine:

• run_script(code: "..."): Runs inline code.
• run_script(file: "..."): Runs a .py file from disk.
• run_script(..., timeout_secs: int): Sets a timeout (default 120s, max 600s).

open_idb(path: "~/samples/malware")

# Background analysis example
analyze_funcs(background: true)   # returns task_id
task_status(task_id: "analyze-1") # poll progress

# Scripting example
run_script(code: "import idautils\nfor f in idautils.Functions():\n    print(hex(f))")

Use open_idb to load a database or a binary file for analysis.

Supported Formats

• IDA Databases: .i64 or .idb files.
• Raw Binaries: Mach-O, ELF, or PE files.

Behavior for Raw Binaries

• Raw binaries are automatically analyzed and saved as a .i64 file in the same directory as the input.
• If a .i64 file already exists for that binary, it is opened directly to save time.
• If a sibling .dSYM file exists and no .i64 is present, DWARF debug information is loaded automatically.

Rebuilding Analysis

If you have modified the input binary or want to overwrite a stale analysis, set rebuild=true.

Closing Databases

Always call close_idb when finished to release file locks. In multi-client environments (like HTTP/SSE), ensure you use the close_token provided by open_idb to coordinate closing.

# Example conceptual usage
open_idb(path="/path/to/binary", rebuild=true)

The project uses just commands to run various integration tests. Note that all integration tests (except unit tests) require IDA Pro with a valid license to be installed and running. You must run cargo build before executing integration tests.

Available test commands:

• just test: Runs Stdio JSONL integration tests.
• just test-http: Runs HTTP/SSE integration tests.
• just test-script: Runs IDAPython script execution tests.
• just test-elicitation: Runs the open_idb auto-background elicitation test.
• just test-dsc <path>: Runs the DSC (dyld shared cache) loading test using a specific path.
• just cargo-test: Runs standard Rust unit tests (does not require IDA).

just test         # Stdio JSONL integration test
just test-http    # HTTP/SSE integration test
just test-script  # IDAPython script execution test
just test-elicitation # open_idb auto-background elicitation test
just test-dsc /path/to/dyld_shared_cache_arm64e  # DSC loading test
just cargo-test   # Unit tests (no IDA required)