zboralski/ida-headless-mcp

Headless IDA Pro binary analysis via Model Context Protocol. Go orchestrates multi-session concurrency while Python workers handle IDA operations.
Architecture
**Key features:**
- Multi-session concurrency via process isolation
- 52 MCP tools for binary analysis
- Automatic session timeouts (4 hours default, configurable)
- Paginated results with configurable limit (default 1000)
- Il2CppDumper metadata import for Unity games
- unflutter metadata import for Flutter/Dart apps
Prerequisites
1. **IDA Pro 9.0+ or IDA Essential 9.2+**
2. **idalib**: install and activate:
See IDA as a Library documentation.
3. **Go 1.21+** with protoc tools:
4. **Python 3.10+** with dependencies:
5. **Optional: Il2CppDumper** for Unity game analysis
6. **Optional: unflutter** for Flutter/Dart app analysis
Installation
This runs idalib setup, installs Python dependencies, and builds the server.
For manual setup or troubleshooting:
Usage
Start Server
Server starts running on port 17300 (configurable via config.json, env, or --port), exposing both transports:
- Streamable HTTP (recommended): http://localhost:17300/
- SSE compatibility endpoint: http://localhost:17300/sse
Configure Claude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json:
Restart Claude Desktop after editing.
Configure Claude Code
Copy .claude/settings.json to ~/.claude/settings.json to grant access to all IDA MCP tools.
Basic Workflow
Flutter/Dart Import
The import_flutter tool reads structured JSON metadata from unflutter. It creates Dart class structs, function definitions with typed signatures, and annotates THR/PP/string reference comments in a single pass.
Use tools/list via MCP to see all available tools.
Configuration
Command line flags:
Environment variables (overridden by CLI flags):
Development
Build
Testing
Install test dependencies:
Run tests:
Interactive Testing
Use MCP Inspector:
Project Structure
Adding New Tools
1. Add RPC to proto/ida/worker/v1/ida_service.proto
2. Regenerate: make proto
3. Implement in python/worker/ida_wrapper.py
4. Add handler in python/worker/connect_server.py
5. Register MCP tool in internal/server/server.go
Session Lifecycle
1. Client calls open_binary(path)
2. Go creates session in registry (UUID)
3. Go spawns Python worker subprocess
4. Worker creates Unix socket at /tmp/ida-worker-{id}.sock
5. Worker opens IDA database with idalib
6. Go creates Connect RPC clients over socket
7. Subsequent tool calls proxy to worker via Connect
8. Watchdog monitors idle time (default: 4 hours)
9. On timeout or close_binary: save database, kill worker, cleanup