ida-free-mcp

MCP bridge for IDA Free 9.5 on Windows x64. Provides 96 tools for live analysis and editing, with stdio and Streamable HTTP transports. Does not require IDAPython.

Version 0.4.0 uses Windows messages to dispatch requests on IDA's main thread and an event to notify the client of completion. It has no idle polling timer. JSON mailboxes still carry request/response data. Older polling plugins remain compatible with the Python client. See measurements for latency results.

Setup

Install Python 3.11+ and the Microsoft Visual C++ x64 runtime. Download the Windows archive from Releases, or build the native plugin from source first.

.\setup.ps1 -Python python
.\start.ps1 -Database C:\analysis\first.i64 -Channel first

Add the generated client-all.json to your agent's MCP settings. If IDA is installed elsewhere, pass --ida 'D:\IDA Free 9.5\ida.exe' to the launcher. You can also pass an executable instead of an existing database; complete the loading dialogs in IDA.

For a custom installation and automatic merge into a JSON MCP client config:

.\setup.ps1 -Ida 'D:\IDA Free 9.5\ida.exe' -McpConfig 'C:\path\to\client-config.json'

Only configs with the mcpServers JSON format are supported by the merger. Other entries and settings are preserved; existing files get a numbered .bak backup. The installer reuses its virtual environment on repeated runs and remembers the selected IDA path locally. It checks IDA 9.5, x64 binaries, Python and dependencies.

To diagnose installation or connections:

.\.venv\Scripts\python.exe .\doctor.py
.\.venv\Scripts\python.exe .\doctor.py --json

The report checks the config and lists running channels, database paths, plugin versions, readiness and unresponsive instances. An idle installation is a warning, not an error. --no-probe skips live connections. Session tokens are not included.

The launcher creates a local IDA profile with the plugin. It does not write to Program Files or change global IDA settings. Restart through the launcher after updating the DLL; existing windows keep their loaded version. When upgrading, replace the previous MCP entry with the newly generated client-all.json. The plugin, server and config key are named ida_free_mcp; environment variables use the IDA_FREE_MCP_ prefix.

Related MCP server: ida-pro-mcp-dsh

Multiple databases

Start one IDA process per database with different channel names:

.\.venv\Scripts\python.exe .\launch.py --channel second C:\analysis\second.i64

One MCP connection serves all channels. Call list_instances, check the database paths, then include instance in each call:

{"instance": "first", "address": "0x140001010"}

Calls without an instance are rejected when several channels are running. Separate windows can process requests concurrently; operations in one window are serialized. Do not open the same physical database in two IDA processes.

Tools

Use your MCP client's tool list for the full catalog and schemas. The tools cover:

• disassembly, functions, control flow, references, strings, imports and searches;

• names, comments, types, stack frames, segments, data and operand formatting;

• byte/assembly patches, original-byte reads and patch restoration;

• decompilation and reading the active pseudocode view;

• debugger control, breakpoints, integer registers and mapped process memory;

• byte/function comparisons across instances and bounded batch edits;

• IDC expressions/scripts and registered IDA UI actions.

Addresses are hex strings or exact symbol names. Follow next_offset and next_address for paginated results. Byte patches require matching expected_hex. Batch edits stop on failure and return complete, completed, failed_index and error; they are not transactions. Composite reads are not atomic snapshots.

Batch edits hold the channel lock for their whole duration, so other bridge clients cannot interleave operations. This does not lock the IDA GUI and does not provide rollback. A native session change stops remaining items. Cancelling the MCP call prevents subsequent items after the current operation finishes.

An incomplete batch also returns item_status (rejected, unknown or not_started), request_id when available, and indices in not_attempted. failed_index identifies the item without confirmed success; it does not prove the edit failed. Transport failures can leave an applied edit without acknowledgement. Read that address before resuming and never replay the confirmed prefix. retry_safe is false for incomplete batches; request IDs identify attempts, not replayable tokens.

imports and callees accept offset / limit and return next_offset (-1 means end). callees also reports scan_limit_reached when a function exceeds the instruction scan bound. Call graphs expose truncation_reasons and unavailable_functions so partial results are explicit.

HTTP

Stdio is the default. For a client requiring Streamable HTTP:

$env:IDA_FREE_MCP_TOKEN = (& .\.venv\Scripts\python.exe -c 'import secrets; print(secrets.token_urlsafe(32))')
.\.venv\Scripts\python.exe .\server.py --bridge-root .\runtime --transport http --port 18745

Connect to http://127.0.0.1:18745/mcp/ with Authorization: Bearer <token>. The server binds to loopback and rejects browser Origin headers. Legacy SSE is not implemented. A remote/cloud agent needs a local MCP connector.

Trust and limitations

IDC and UI actions have IDA's privileges, including file access and process execution. This is not a sandbox. Keep runtime private and only connect trusted agents. Treat analyzed strings, comments and pseudocode as data, not instructions.

Free decompilation uses Hex-Rays' cloud service and may show consent/error dialogs. The bridge does not bypass licensing or dialogs. read_pseudocode reads the active view. Debugger start executes the selected input program. Debug memory reads are limited to addresses mapped in the database; register tools handle integer values.

A timed-out mutation may have executed. Inspect the database before retrying. Long IDC scripts block IDA and cannot be safely cancelled. Do not call qexit or unload the bridge from an IDC callback: closing from a bridge callback can hang IDA. Close the application normally instead.

Build

Requires MSVC C++ Build Tools, Windows SDK and CMake 3.25+.

git clone --depth 1 --branch v9.5.0-release https://github.com/HexRaysSA/ida-sdk.git sdk
.\build.ps1 -IdaSdk "$PWD\sdk"

The output is bin/ida_free_mcp.dll. The SDK, IDA binaries and test databases are not included in this repository. The DLL is not Authenticode-signed.

Tests

python -m pip install -r requirements.txt pytest==9.2.0
python -m pytest -q

Windows CI runs the unit/transport tests. Live tests need local IDA and disposable databases; see testing notes. Functional test coverage does not guarantee correctness for every input, processor or UI context.

License

Project code: MIT. Built against the official IDA SDK 9.5 (04c0a982c80fd08388e7a3c26ff711fc1c38344d); its MIT notice is included. IDA itself is a separate Hex-Rays product. The native bridge uses Windows and IDA APIs; the companion uses the official MCP Python SDK.