# IDA-MCP

MCP server that runs inside **IDA Pro 9.4** so tools like Cursor / Claude / Cline can talk to your open IDB over HTTP.

Default listen address: `127.0.0.1:8765`  
Stack: IDAPython + Hex-Rays (when present). No extra pip deps inside IDA.

## Install

```powershell
.\install.ps1 -IdaPath "C:\Program Files\IDA Professional 9.4"
```

Copies the plugin to `%APPDATA%\Hex-Rays\IDA Pro\plugins\`.

Uninstall:

```powershell
.\uninstall.ps1
```

## Usage

1. Open IDA 9.4 and load an IDB
2. **Edit → Plugins → IDA-MCP → Start** (or `Ctrl-Alt-M` to toggle)
   - Stop: **Edit → Plugins → IDA-MCP → Stop** (or `Ctrl-Alt-M` again)
3. Point your MCP client at `http://127.0.0.1:8765/mcp`

### Cursor

`%USERPROFILE%\.cursor\mcp.json` or project `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "ida-mcp": {
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}
```

If you set a token in config:

```json
{
  "mcpServers": {
    "ida-mcp": {
      "url": "http://127.0.0.1:8765/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}
```

More examples under [`examples/`](examples/).

### Smoke check

```powershell
Invoke-RestMethod http://127.0.0.1:8765/health
```

Try: *call `get_database_info`*, then `list_functions` / `decompile_function`.

## Config

`%LOCALAPPDATA%\IDA-MCP\config.json`

```json
{
  "host": "127.0.0.1",
  "port": 8765,
  "token": "",
  "allow_write": false,
  "allow_patch": false,
  "allow_execution": false,
  "max_read_size": 1048576,
  "max_call_depth": 20,
  "log_level": "INFO"
}
```

Env vars override the file: `IDA_MCP_HOST`, `IDA_MCP_PORT`, `IDA_MCP_TOKEN`, `IDA_MCP_ALLOW_WRITE`, `IDA_MCP_ALLOW_PATCH`, `IDA_MCP_ALLOW_EXECUTION`, …

Logs: `%LOCALAPPDATA%\IDA-MCP\ida-mcp.log`

### Defaults

| | |
| --- | --- |
| Bind | localhost only |
| Rename / comments / types | off (`allow_write`) |
| Byte patching | off (`allow_patch`) |
| `execute_idapython` | off (also needs a token) |
| Memory reads | capped at 1 MiB |

Don't bind `0.0.0.0` without a token — the server refuses that.

## How it works

HTTP JSON-RPC (Streamable HTTP) in a background thread inside IDA. Tool handlers schedule IDA API calls with `ida_kernwin.execute_sync` so the UI doesn't get trashed from worker threads.

Stdlib only in-process; the optional `mcp` package in `requirements.txt` is for external tooling/tests, not required by the plugin.

See [`docs/architecture.md`](docs/architecture.md).

## Tools (high level)

There are ~57 tools. The useful ones day-to-day:

- DB: `get_database_info`, `get_entry_points`
- Functions: `list_functions`, `get_function*`, `get_disassembly`, `decompile_function`
- Xrefs / graph: `get_xrefs_*`, `get_callers`, `get_callees`, `trace_call_path`
- Imports / strings: `list_imports`, `find_import`, `list_strings`, `find_string`
- Search / memory: `search_bytes`, `search_text`, `read_memory`
- Analysis helpers: `analyze_function`, `summarize_function`

Writes and patches are separate and gated. Full list: [`docs/tools.md`](docs/tools.md).

Resources: `ida://database`, `ida://function/0x…`, `…/pseudocode`, `…/disassembly`.

## After code changes

Either restart IDA, or run `scripts/reload_ida_mcp.py` via **File → Script file**.

## Tests

```powershell
pip install pytest
pytest tests -q
```

Live checks (IDA must be running with MCP up): `tests/_live_mcp_check.py`, `tests/_live_full_test.py`.

## Layout

```text
ida_plugin/          plugin entry + package
install.ps1          Windows installer
docs/                architecture / tools / install notes
examples/            MCP client configs
.cursor/skills/      Cursor skill for using the tools
tests/
```

## License

MIT — see [LICENSE](LICENSE).