# 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](docs/testing.md) 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.

```powershell
.\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:

```powershell
.\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:

```powershell
.\.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.

## Multiple databases

Start one IDA process per database with different channel names:

```powershell
.\.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:

```json
{"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:

```powershell
$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+.

```powershell
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

```powershell
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](docs/testing.md). Functional test coverage does not
guarantee correctness for every input, processor or UI context.

## License

Project code: [MIT](LICENSE). Built against the official IDA SDK 9.5
(`04c0a982c80fd08388e7a3c26ff711fc1c38344d`); its [MIT notice](licenses/ida-sdk.txt)
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.