IDAPro-MCP Server

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