# IDAPro-MCP Server

Exposes IDA Pro's analysis capabilities through the Model Context Protocol (MCP). Provides 247 tools for reverse engineering and binary analysis. Supports headless operation via IDA's `idalib` (no GUI required) and optional GUI plugin mode for interactive IDA Pro sessions.

## Requirements

- Python 3.10 or later
- IDA Pro 8.3 or later (for headless idalib mode)
- The `mcp` Python package (installed automatically)

## Installation

```
pip install -e .
```

This installs the `IDAPro-MCP` package in editable mode, making the `IDAPro-MCP` command available.

## Running the Server

### Stdio transport (default, for MCP clients)

```
IDAPro-MCP
```

The server listens on stdin/stdout using the MCP protocol. Most MCP clients connect this way.

### HTTP/SSE transport

```
IDAPro-MCP --http --port 8744
```

Useful for remote access or when multiple clients need to share one server instance.

### Tool exposure modes

The server supports three levels of tool visibility. This affects which tools the MCP client sees during `list_tools`.

| Mode | Visible tools | Use case |
|------|---------------|----------|
| `dynamic` (default) | 5 discovery tools | Minimizes context window; tools load on demand via `load_toolset` |
| `aliased` | 5 meta-tools + 5 discovery | Groups 247 operations into 5 parameterized tools (inspect, analyze, modify, debug, search) |
| `full` | All 247 tools | Maximum discoverability; all tools visible at once |

```
IDAPro-MCP --tool-mode dynamic
IDAPro-MCP --tool-mode aliased
IDAPro-MCP --tool-mode full
```

### Unsafe operations

Some tools modify the database (patch bytes, rename, define functions) or control the debugger. These are hidden unless `--unsafe` is passed:

```
IDAPro-MCP --unsafe
```

### All flags

```
IDAPro-MCP --help
```

Output:

```
usage: __main__.py [-h] [--unsafe] [--http] [--host HOST] [--port PORT]
                   [--install] [--uninstall]
                   [--tool-mode {dynamic,aliased,full}]

options:
  -h, --help            show this help message and exit
  --unsafe              Enable unsafe operations (debugger, destructive tools)
  --http                Use HTTP/SSE transport instead of stdio
  --host HOST           Host to bind HTTP server to (default: 127.0.0.1)
  --port PORT           Port for HTTP server (default: 8744)
  --install             Install the IDA Pro plugin
  --uninstall           Uninstall the IDA Pro plugin
  --tool-mode           Tool exposure mode: 'dynamic' (default, 3 tools
                        initially), 'aliased' (5 meta-tools), 'full' (all 247
                        tools)
```

## Tool Categories

The 247 tools are organized into 24 categories. Discovery tools (`discover_categories`, `load_toolset`, `open_target`, `close_target`, `list_resources`) are always visible. Other tools become available after loading their category.

| Category | Tools | Description |
|---|---|---|
| core | 11 | Server health, IDB operations, instance management |
| functions | 28 | Query, analyze, create, delete, and modify functions |
| memory | 18 | Read bytes, ints, floats, strings; data flags; address navigation |
| instructions | 17 | Disassembly, operands, mnemonics, flow break checks |
| search | 8 | Search bytes, text, immediates, regex across the binary |
| imports_exports | 11 | List imports, exports, and entry points |
| segments | 13 | List, look up, and inspect memory segments |
| xrefs | 17 | Cross-references: code/data, callers/callees, reads/writes |
| strings | 8 | List and search strings; ASCII and Unicode |
| analysis | 4 | Function analysis, binary survey, data flow tracing |
| decompilation | 6 | Decompile, disassemble, microcode, flowchart, basic blocks |
| types | 10 | Query, declare, apply, infer types; structs, enums |
| names | 12 | Get, set, delete, demangle names; visibility flags |
| heads | 3 | Enumerate defined items, check if code or data |
| comments | 11 | Set, get, delete comments and bookmarks |
| modification | 6 | Define/undefine functions, rename, patch bytes/asm, create data |
| stack | 3 | Inspect and declare stack variables |
| patches | 5 | Revert patches, list patches, undo/redo |
| signatures | 5 | Generate signatures, apply FLIRT |
| python | 2 | Execute arbitrary Python in IDA context |
| debugger | 18 | Start/stop debugger, breakpoints, registers, memory read/write |
| info | 16 | Binary metadata, architecture, hashes, analysis status |
| hooks | 5 | Install and remove IDA event hooks |
| flow | 5 | Call graphs, cyclomatic complexity, critical paths |

### Aliased tools (--tool-mode aliased)

When using aliased mode, five parameterized tools group related operations:

- **inspect** — inspect functions, segments, strings, memory, names, types, imports, exports
- **analyze** — analyze function, binary survey, component analysis, data flow trace
- **modify** — patch bytes, patch asm, rename, define function, make data, set comment, undo/redo
- **debug** — start/stop debugger, step, breakpoints, registers, memory
- **search** — search bytes, text, immediates, regex, strings

Each takes an `artifact` and `action` parameter to select the specific operation.

## Architecture

```
MCP Client
    |  stdio / HTTP SSE (MCP Protocol)
    v
+-----------------------------------------+
| IDAPro-MCP Server                       |
|  - 247 tools across 24 categories       |
|  - Dynamic tool registry                |
|  - Instance router                      |
|  - Session manager                      |
+--+-------+-------+-------+--------------+
   |       |       |       |  HTTP JSON-RPC
   v       v       v       v
 idalib   idalib   idalib  IDA GUI
 (bin1)   (bin2)   (bin3)  (plugin)
```

The server routes tool calls to the appropriate IDA Pro session. Each session can be either:
- A headless `idalib` subprocess (spawned per binary via `open_target`)
- A GUI IDA Pro instance (connected via the optional plugin)

### Multi-instance support

The server can manage multiple IDA Pro sessions simultaneously. Each session has a unique `instance_id`. Tool calls target a specific instance, or the most recently active one if none is specified.

## Usage

### Opening a binary

The `open_target` tool starts a headless idalib session for a binary file:

```
open_target(path="/path/to/binary.exe")
```

Returns an `instance_id` that subsequent tools can use to target this session.

### Instance-aware tool calls

Most tools accept an `instance_id` parameter. If omitted, the most recently active instance is used.

### Dynamic tool loading (default mode)

In default `dynamic` mode, only discovery tools are initially visible:

1. Call `discover_categories()` to see available categories
2. Call `load_toolset(category="functions")` to load a category's tools
3. Loaded tools become visible for subsequent calls

After `open_target()` succeeds, seven commonly used categories (functions, memory, search, info, segments, xrefs, strings) load automatically.

### IDA plugin mode

Install the plugin to connect an interactive IDA Pro GUI session:

```
IDAPro-MCP --install
```

This copies `idapro_mcp_plugin.py` to IDA's plugins directory. After restarting IDA, the plugin registers the GUI session with the MCP server, allowing tools to operate on the currently open database.

## Resources

The server exposes 34 read-only resources through MCP's resource protocol:

- `ida://idb/metadata` — IDB metadata
- `ida://idb/segments` — Memory segments
- `ida://function/{addr}` — Function details
- `ida://function/pseudocode/{addr}` — Decompiled pseudocode
- `ida://strings` — All strings
- `ida://import/{name}` — Import details
- and 28 more

Resources are automatically available when a binary is open.

## Project structure

```
IDAPro-MCP/
  pyproject.toml
  README.md
  src/IDAPro_MCP/
    __init__.py
    __main__.py          # CLI entry point
    server.py            # MCP server, transports, handler registration
    framework.py         # @tool, @unsafe decorators
    sync.py              # @idasync thread safety
    compat.py            # IDA 8.3-9.3 version shims
    utils.py             # Address parsing, ID generation
    tool_registry.py     # 24 categories, 5 aliased tools, dynamic loading
    api_core.py          # Server health, IDB open/close, instance management
    api_query.py         # Function lookup, flags, locals, create/delete
    api_memory.py        # Byte/int/float/string reads, data flags
    api_instructions.py  # Mnemonics, operands, flow checks
    api_search.py        # Binary search tools
    api_import_export.py # Import/export listing
    api_segments.py      # Segment operations
    api_xrefs.py         # Cross-references
    api_strings.py       # String listing and search
    api_analysis.py      # Function analysis, binary survey
    api_heads.py         # Head enumeration
    api_names.py         # Symbol name operations
    api_hexrays.py       # Decompilation, disassembly, microcode, flowchart
    api_types.py         # Type system: query, declare, structs, enums
    api_modify.py        # Patch bytes/asm, rename, define/undefine
    api_comments.py      # Comments and bookmarks
    api_stack.py         # Stack frame inspection
    api_patch.py         # Patch management, undo/redo
    api_sigmaker.py      # Signature generation, FLIRT
    api_python.py        # Python execution in IDA context
    api_debug.py         # Debugger control
    api_entries.py       # Entry point operations
    api_info.py          # Binary metadata, hashes, architecture
    api_hooks.py         # Event hook installation
    api_flow.py          # Call graphs, complexity metrics
    api_resources.py     # 34 MCP resource URIs
    idalib/
      __init__.py
      server.py          # idalib subprocess JSON-RPC server
      session_manager.py # Subprocess lifecycle
      supervisor.py      # Health monitoring, idle timeout
    router/
      __init__.py
      registry.py        # Instance registry
      router.py          # Tool routing to correct instance
    zeromcp/
      __init__.py        # JSON-RPC protocol helpers
  tests/
    test_tool_inventory.py
```

## Compatibility

- Python 3.10, 3.11, 3.12
- IDA Pro 8.3 through 9.3 (headless idalib mode)
- The mcp SDK version 1.26.0 (or compatible 1.x)

## License

MIT