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