ida-headless-mcp

Purpose

ida-headless-mcp is a headless IDA Pro binary analysis server based on the Model Context Protocol (MCP). It allows clients to remotely invoke IDA Pro's binary analysis capabilities through the MCP protocol, and provides metadata import functionality for reverse engineering Unity and Flutter/Dart applications.

Main Capabilities

• Headless analysis: Provides IDA Pro binary analysis through MCP, without the need for GUI operations.
• Multi-session concurrency: Achieves multi-session concurrent processing through process isolation.
• Rich toolset: Built-in 52 MCP tools for binary analysis.
• Session timeout management: Automatic session timeout, default 4 hours, configurable.
• Paginated results: Supports paginated result returns, default 1000 per page, configurable.
• Unity metadata import: Imports metadata through Il2CppDumper, for Unity game analysis.
• Flutter/Dart metadata import: Imports metadata through unflutter, for Flutter/Dart application analysis. The import_flutter tool reads the structured JSON metadata generated by unflutter, creates Dart class structures and function definitions with type signatures in a single pass, and annotates THR/PP/string reference comments.

Usage

Environment Requirements

• IDA Pro 9.0+ or IDA Essential 9.2+
• idalib: needs to be installed and activated, execute ./scripts/setup_idalib.sh; see the IDA as a Library documentation.
• Go 1.21+ and the protoc tool:make install-tools
• Python 3.10+ and dependencies:pip3 install -r python/requirements.txt
• Optional: Il2CppDumper (for Unity game analysis)
• Optional: unflutter (for Flutter/Dart application analysis):

  git clone https://github.com/zboralski/unflutter.git
  cd unflutter && make install
  

Installation and Startup

Run the idalib setup, install Python dependencies, and build the server (this completes all configuration). The server runs on port 17300 by default, and can be configured through config.json, environment variables, or --port . Two transport methods are exposed:

• Streamable HTTP (recommended):http://localhost:17300/
• SSE-compatible endpoint:http://localhost:17300/sse

Client Configuration

• Claude Desktop: Edit ~/Library/Application Support/Claude/claude_desktop_config.json, and restart Claude Desktop after editing.
• Claude Code: Copy .claude/settings.json to ~/.claude/settings.jsonto authorize access to all IDA MCP tools.

Through MCP's tools/list , you can view all available tools.

Session Lifecycle

1. The client calls open_binary(path).
2. Go creates a session (UUID) in the registry.
3. Go starts a Python worker subprocess.
4. The worker creates a Unix socket at /tmp/ida-worker-{id}.sock .
5. The worker opens the IDA database using idalib.
6. Go creates a Connect RPC client through the socket.
7. Subsequent tool calls are proxied to the worker through Connect.
8. A watchdog monitors idle time (default 4 hours).
9. On timeout or when calling close_binary : save the database, terminate the worker, and clean up.
10. Session metadata is saved under <database_directory>/sessions , and can be automatically restored after the server restarts.

Extending New Tools

1. Add an RPC in proto/ida/worker/v1/ida_service.proto .
2. Regenerate:make proto.
3. Implement in python/worker/ida_wrapper.py .
4. Add a handler in python/worker/connect_server.py .
5. In internal/server/server.go Register the MCP tool in.

Use cases

• Headless, programmable reverse engineering of binary files.
• Analyze Unity games (via Il2CppDumper metadata import).
• Analyze Flutter/Dart applications (via unflutter metadata import).
• Scenarios requiring multi-session concurrent handling of multiple binary analysis tasks.

Limitations and notes

• Requires valid authorization and installation of IDA Pro 9.0+ or IDA Essential 9.2+, as well as idalib.
• Requires development dependencies such as Go 1.21+ and Python 3.10+.
• Official materials do not provide further information on fees, pricing, or platform compatibility.

Related projects

• LaurieWired/GhidraMCP
• mrexodia/ida-pro-mcp
• cnitlrt/headless-ida-mcp-server
• Metadata dump tools: Perfare/Il2CppDumper (for import_il2cpp), zboralski/unflutter (for import_flutter)

Troubleshooting

• Worker fails to start: run ./scripts/setup_idalib.sh.
• Socket timeout: check the Python worker logs; the worker may have crashed during initialization.
• Port already in use: you can change the port.
• Session not found: the session may have timed out; use list_sessions to check active sessions.

The specific contents of command-line flags and environment variables are not officially provided as a complete list and are not available for now.