IDA-MCP
IDA-MCP (FastMCP + Multi-instance Coordinator)
- Each IDA instance starts a FastMCP server (
/mcp) - The first instance occupies
127.0.0.1:11337as the coordinator, maintaining a memory registry and supporting tool forwarding - Subsequent instances automatically register with the coordinator; no need to share files or manually configure ports
- Unified access / aggregation of instance tools via a modular proxy (MCP clients can start it via command/args)
Architecture
The project uses a modular architecture:
Core Infrastructure
rpc.py-@tool/@resource/@unsafedecorators and registrationsync.py-@idaread/@idawriteIDA thread synchronization decoratorsutils.py- Address parsing, pagination, pattern filtering utilitiescompat.py- IDA 8.x/9.x compatibility layer
API Modules (IDA Backend)
api_core.py- IDB metadata, function/string/global listsapi_analysis.py- Decompilation, disassembly, cross-referencesapi_memory.py- Memory reading operationsapi_types.py- Type operations (prototypes, local types)api_modify.py- Comments, renamingapi_stack.py- Stack frame operationsapi_debug.py- Debugger control (marked unsafe)api_resources.py- MCP Resources (ida://URI patterns)
Key Features
- Decorator Chain Pattern:
@tool+@idaread/@idawritefor clean API definitions - Batch Operations: Most tools accept lists for batch processing
- MCP Resources: REST-like
ida://URI patterns for read-only data access - Multi-instance Support: Coordinator on port 11337 manages multiple IDA instances
- IDA 8.x/9.x Compatible: Compatibility layer handles API differences
Current Tools
Core Tools (api_core.py)
check_connection– Health check (ok/count)list_instances– List all registered IDA instancesget_metadata– IDB metadata (hash/arch/bits/endian)list_functions– Paginated function list with optional pattern filterget_function– Find function by name or addresslist_globals– Global symbols (non-functions)list_strings– Extracted stringslist_local_types– Local type definitionsget_entry_points– Program entry pointsconvert_number– Number format conversionlist_imports– List imported functions with module nameslist_exports– List exported functions/symbolslist_segments– List memory segments with permissionsget_cursor– Get current cursor position and context
Analysis Tools (api_analysis.py)
decompile– Batch decompile functions (Hex-Rays)disasm– Batch disassemble functionslinear_disassemble– Linear disassembly from arbitrary addressxrefs_to– Batch cross-references to addressesxrefs_from– Batch cross-references from addressesxrefs_to_field– Heuristic struct field referencesfind_bytes– Search for byte patterns with wildcardsget_basic_blocks– Get basic blocks with control flow
Memory Tools (api_memory.py)
get_bytes– Read raw bytesget_u8/get_u16/get_u32/get_u64– Read integersget_string– Read null-terminated strings
Type Tools (api_types.py)
declare_type– Create/update local typesset_function_prototype– Set function signatureset_local_variable_type– Set local variable type (Hex-Rays)set_global_variable_type– Set global variable typelist_structs– List all structures/unionsget_struct_info– Get structure definition with fields
Modify Tools (api_modify.py)
set_comment– Batch set commentsrename_function– Rename functionrename_local_variable– Rename local variable (Hex-Rays)rename_global_variable– Rename global symbolpatch_bytes– Patch bytes at addresses
Stack Tools (api_stack.py)
stack_frame– Get stack frame variablesdeclare_stack– Create stack variablesdelete_stack– Delete stack variables
Debug Tools (api_debug.py) - Unsafe
dbg_regs– Get all registersdbg_callstack– Get call stackdbg_list_bps– List breakpointsdbg_start– Start debuggingdbg_exit– Terminate debugdbg_continue– Continue executiondbg_run_to– Run to addressdbg_add_bp– Add breakpointdbg_delete_bp– Delete breakpointdbg_enable_bp– Enable/disable breakpointdbg_step_into– Step into instructiondbg_step_over– Step over instructiondbg_read_mem– Read debugger memorydbg_write_mem– Write debugger memory
MCP Resources (api_resources.py)
ida://idb/metadata– IDB metadataida://functions/ida://functions/{pattern}– Functionsida://function/{addr}– Single function detailsida://strings/ida://strings/{pattern}– Stringsida://globals/ida://globals/{pattern}– Global symbolsida://types/ida://types/{pattern}– Local typesida://segments– Segment listida://imports– Import listida://exports– Export listida://xrefs/to/{addr}– Cross-references to addressida://xrefs/from/{addr}– Cross-references from addressida://memory/{addr}?size=N– Read memory
Directory Structure
IDA-MCP/
ida_mcp.py # Plugin entry: start/stop SSE server + register coordinator
ida_mcp/
__init__.py # Package initialization, auto-discovery, exports
config.py # Configuration loader (config.conf parser)
config.conf # User configuration file
rpc.py # @tool/@resource/@unsafe decorators
sync.py # @idaread/@idawrite thread sync
utils.py # Utility functions
compat.py # IDA 8.x/9.x compatibility layer
api_core.py # Core API (metadata, lists)
api_analysis.py # Analysis API (decompile, disasm, xrefs)
api_memory.py # Memory API
api_types.py # Type API
api_modify.py # Modification API
api_stack.py # Stack frame API
api_debug.py # Debugger API (unsafe)
api_resources.py # MCP Resources
registry.py # Coordinator / multi-instance registration
proxy/ # stdio-based MCP proxy
__init__.py # Proxy module exports
ida_mcp_proxy.py # Main entry point (stdio MCP server)
_http.py # HTTP helpers for coordinator communication
_state.py # State management and port validation
proxy_core.py # Core forwarding tools
proxy_analysis.py # Analysis forwarding tools
proxy_memory.py # Memory forwarding tools
proxy_types.py # Type forwarding tools
proxy_modify.py # Modification forwarding tools
proxy_stack.py # Stack frame forwarding tools
proxy_debug.py # Debug forwarding tools
http/ # HTTP-based MCP proxy (auto-started, reuses stdio proxy)
__init__.py # HTTP module exports
http_server.py # HTTP transport wrapper (reuses ida_mcp_proxy.server)
mcp.json # MCP client configuration (both modes)
README.md # README
requirements.txt # fastmcp dependencies
Startup Steps
- Copy
ida_mcp.py+ida_mcpfolder to IDA'splugins/. - Open target binary, wait for analysis to complete.
- Trigger plugin via menu / shortcut: First launch will:
- Select free port (starting from 10000) to run SSE service
http://127.0.0.1:<port>/mcp/ - If 11337 is free → start coordinator; otherwise register with existing coordinator
- Select free port (starting from 10000) to run SSE service
- Trigger plugin again = stop and unregister instance.
Proxy Usage
The proxy simultaneously supports both transport modes - choose whichever works best for your MCP client:
Transport Modes
| Mode | Description | Configuration |
|---|---|---|
| HTTP (recommended) | Auto-started by coordinator, no subprocess needed | Only requires url |
| stdio | MCP client launches subprocess | Requires command and args |
Both modes are always available when the IDA plugin is running.
Proxy Tools:
| Category | Tools |
|---|---|
| Management | check_connection, list_instances, select_instance |
| Core | list_functions, get_metadata, list_strings, list_globals, list_local_types, get_entry_points, get_function |
| Analysis | decompile, disasm, linear_disassemble, xrefs_to, xrefs_from, find_bytes, get_basic_blocks |
| Modify | set_comment, rename_function, rename_global_variable, rename_local_variable |
| Memory | get_bytes, get_u8, get_u16, get_u32, get_u64, get_string |
| Types | set_function_prototype, set_local_variable_type, set_global_variable_type, declare_type |
| Debug | dbg_start, dbg_continue, dbg_step_into, dbg_step_over, dbg_regs, dbg_add_bp, dbg_delete_bp, ... |
You can use it on Codex / Claude Code / LangChain / Cursor / VSCode / etc - any MCP client.
Configuration File
Edit ida_mcp/config.conf to customize settings:
# Coordinator settings
# coordinator_host = "127.0.0.1"
# coordinator_port = 11337
# HTTP proxy settings
# http_host = "127.0.0.1" # Use 0.0.0.0 for remote access
# http_port = 11338
# http_path = "/mcp"
# IDA instance settings
# ida_default_port = 10000
# General settings
# request_timeout = 30
# debug = false
Method 1: HTTP Mode (Recommended)
HTTP proxy auto-starts when IDA plugin loads. Client only needs URL - no subprocess required.
Claude / Cherry Studio / Cursor example:
{
"mcpServers": {
"ida-mcp": {
"url": "http://127.0.0.1:11338/mcp"
}
}
}
LangChain example:
{
"mcpServers": {
"ida-mcp": {
"transport": "streamable-http",
"url": "http://127.0.0.1:11338/mcp"
}
}
}
VSCode example:
{
"servers": {
"ida-mcp": {
"url": "http://127.0.0.1:11338/mcp"
}
}
}
Method 2: stdio Mode
Client launches proxy as subprocess. Useful when HTTP is not available.
Claude / Cherry Studio / Cursor example:
{
"mcpServers": {
"ida-mcp-proxy": {
"command": "path of python (IDA's python)",
"args": ["path of ida_mcp/proxy/ida_mcp_proxy.py"]
}
}
}
VSCode example:
{
"servers": {
"ida-mcp-proxy": {
"command": "path of python (IDA's python)",
"args": ["path of ida_mcp/proxy/ida_mcp_proxy.py"]
}
}
}
⚠️ Note: Using VSCode Copilot may result in your account being banned.
Dependencies
Need to install using IDA's Python environment:
python -m pip install -r requirements.txt
Development
It's not about having many tools, but about having precise ones; the power of the API is what truly matters. Additionally, the tools should be comprehensive, and the more tools there are, the more obstacles there are for the model to call them. If certain tools can be achieved through existing ones, then those tools are unnecessary. What I need are the missing tools—the ones that existing tools cannot accomplish.
Future Plans
Add UI interface, support internal model calls, add multi-agent A2A automated reverse engineering functionality after langchain officially updates to 1.0.0.