# IDA Pro MCP Bridge

An **MCP (Model Context Protocol) server** plus an **in-IDA bridge plugin** that
let an AI assistant (Claude Desktop, or any MCP client) autonomously inspect and
control **IDA Pro** — decompilation, disassembly, cross-references, renaming,
typing, patching, searching, the debugger, and arbitrary IDAPython.

## How it works

```
Claude Desktop  ──stdio (MCP)──►  ida_mcp/server.py
                                        │  JSON-RPC over HTTP (127.0.0.1:13337)
                                        ▼
                          ida_mcp_server_plugin.py  (runs inside IDA Pro)
                                        │  execute_sync → IDA main thread
                                        ▼
                                 IDA 9.x database
```

The bridge is split in two because IDA's API only exists **inside** the IDA
process and is **not thread-safe**. The plugin runs an HTTP JSON-RPC server and
marshals every call onto IDA's main thread with `ida_kernwin.execute_sync`. The
MCP server is an ordinary process that forwards tool calls to that endpoint, so
it can be launched and supervised by the MCP client.

## Think of it like...

A **remote control with a receiver**. The plugin is the *receiver* bolted inside
IDA — it can actually press IDA's buttons. The MCP server is the *handset* Claude
holds; every button on the handset sends a signal to the receiver, which does the
real work on IDA's own control panel and reports back.

## Requirements

- IDA Pro **9.x** with IDAPython (Hex-Rays optional, enables decompilation)
- Python **3.10+** for the MCP server
- `pip install -r requirements.txt` (`mcp`, `requests`)

## Install

```bash
pip install -r requirements.txt
python install.py            # copies the plugin + registers with Claude Desktop
```

`install.py` will:
1. Copy `ida_mcp_server_plugin.py` into `%APPDATA%\Hex-Rays\IDA Pro\plugins\`.
2. Add an `ida-pro` entry to `%APPDATA%\Claude\claude_desktop_config.json`
   (a timestamped backup is written first).

Then **restart IDA** (the plugin auto-starts its server on load) and **fully quit
and reopen Claude Desktop**. Open any database in IDA and ask Claude to
`check_connection`.

Run steps individually with `python install.py --plugin` or `--claude`.

## Configuration (environment variables)

| Variable | Default | Meaning |
|---|---|---|
| `IDA_MCP_HOST` | `127.0.0.1` | plugin bind address (keep on loopback) |
| `IDA_MCP_PORT` | `13337` | plugin port |
| `IDA_MCP_TOKEN` | *(empty)* | if set, every call needs header `X-MCP-Token` |
| `IDA_MCP_URL` | `http://127.0.0.1:13337` | where the MCP server finds IDA |
| `IDA_MCP_TIMEOUT` | `60` | per-call timeout (seconds) |

## Tools exposed to the assistant

**Program:** `check_connection`, `get_metadata`, `list_segments`,
`list_entry_points`, `list_imports`, `list_exports`

**Functions:** `list_functions`, `get_function`, `decompile_function`,
`disassemble_function`, `disassemble_range`

**Xrefs / names:** `get_xrefs_to`, `get_xrefs_from`, `get_callers`,
`get_callees`, `list_names`, `demangle`

**Data:** `read_bytes`, `read_string`, `get_value`, `list_strings`,
`search_strings`, `search_bytes`

**Edits:** `rename_address`, `set_comment`, `set_function_comment`,
`set_prototype`, `declare_type`, `get_type`, `make_function`,
`delete_function`, `patch_bytes`

**Navigation / types:** `get_current_address`, `jump_to`, `list_local_types`

**Debugger:** `dbg_state`, `dbg_start`, `dbg_stop`, `dbg_continue`,
`dbg_step_into`, `dbg_step_over`, `dbg_add_breakpoint`, `dbg_del_breakpoint`,
`dbg_list_breakpoints`, `dbg_get_registers`, `dbg_read_memory`, `dbg_write_memory`

**Anything else:** `run_ida_script` runs arbitrary IDAPython on IDA's main thread
(set `result` in the script to return a value). `list_bridge_methods` lists the
raw RPC surface.

## Security

The server binds to **loopback only**. `run_ida_script`, `patch_bytes`, and the
debugger write tools grant full control of IDA and can execute arbitrary code, so
**never** expose the port beyond `127.0.0.1`. For shared machines, set
`IDA_MCP_TOKEN` on both the plugin (IDA's environment) and the MCP server.

## Troubleshooting

- **`Cannot reach IDA`** — IDA isn't open, no database is loaded, or the plugin
  didn't start. In IDA, run *Edit ▸ Plugins ▸ IDA MCP Server*, or check the
  Output window for the `[IDA-MCP] ... serving on ...` banner.
- **`Hex-Rays decompiler is not available`** — your IDA lacks the decompiler for
  this architecture; use `disassemble_function` instead.
- **Port in use** — set `IDA_MCP_PORT` (and matching `IDA_MCP_URL`).

---

**Developer:** HaKDMoDz™ · **Version:** 1.0.0 · **Date:** 2026-09-23