loading…
Search for a command to run...
loading…
Headless IDA Pro binary analysis via MCP. Multi-session concurrency with Go orchestration and Python workers. Supports Il2CppDumper and Blutter metadata import
Headless IDA Pro binary analysis via MCP. Multi-session concurrency with Go orchestration and Python workers. Supports Il2CppDumper and Blutter metadata import for Unity and Flutter reverse engineering.
Headless IDA Pro binary analysis via Model Context Protocol. Go orchestrates multi-session concurrency while Python workers handle IDA operations.
┌─────────────────┐
│ MCP Client │ Claude Desktop, Claude Code, CLI
│ (HTTP/SSE) │
└────────┬────────┘
│ http://localhost:17300/
▼
┌─────────────────┐
│ Go Server │ Session registry, worker manager, watchdog
│ (MCP Tools) │
└────────┬────────┘
│ Connect RPC over Unix socket
▼
┌─────────────────┐
│ Python Worker │ IDA + idalib (one per session)
│ (per session) │
└─────────────────┘
Key features:
IDA Pro 9.0+ or IDA Essential 9.2+
idalib: install and activate:
./scripts/setup_idalib.sh
Go 1.21+ with protoc tools:
make install-tools
Python 3.10+ with dependencies:
pip3 install -r python/requirements.txt
Optional: Il2CppDumper for Unity game analysis
Optional: unflutter for Flutter/Dart app analysis
# Install unflutter (provides flutter_meta.json for import_flutter)
git clone https://github.com/zboralski/unflutter.git
cd unflutter && make install
git clone <repo-url>
cd ida-headless-mcp
make setup
This runs idalib setup, installs Python dependencies, and builds the server.
For manual setup or troubleshooting:
./scripts/setup_idalib.sh # Setup idalib (requires IDA Pro/Essential 9.x)
make install-python # Install Python dependencies
make build # Build Go server
./bin/ida-mcp-server
Server starts running on port 17300 (configurable via config.json, env, or --port), exposing both transports:
http://localhost:17300/http://localhost:17300/sseEdit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"ida-headless": {
"url": "http://127.0.0.1:17300/",
"type": "http"
}
}
}
Restart Claude Desktop after editing.
Copy .claude/settings.json to ~/.claude/settings.json to grant access to all IDA MCP tools.
1. open_binary(path="/path/to/binary.so")
→ {"session_id": "abc123", "has_decompiler": true}
2. run_auto_analysis(session_id="abc123")
→ {"completed": true}
3. get_entry_point(session_id="abc123")
→ {"address": 4198400}
4. get_decompiled_func(session_id="abc123", address=4198400)
→ {pseudocode...}
5. get_functions(session_id="abc123")
→ {"functions": [...], "count": 1523}
6. close_binary(session_id="abc123")
→ {"success": true}
1. Run unflutter on the target: unflutter meta libapp.so
2. open_binary(path="libapp.so")
3. import_flutter(session_id="...", meta_json_path="flutter_meta.json")
→ {"functions_created": 9926, "structs_created": 2090,
"signatures_applied": 9926, "comments_set": 34172}
4. run_auto_analysis(session_id="...")
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.
Command line flags:
./bin/ida-mcp-server \
--port 17300 \
--max-sessions 10 \
--session-timeout 4h \
--worker python/worker/server.py \
--debug
Environment variables (overridden by CLI flags):
IDA_MCP_PORT=17300
IDA_MCP_SESSION_TIMEOUT_MIN=240
IDA_MCP_MAX_SESSIONS=10
IDA_MCP_WORKER=/custom/worker.py
IDA_MCP_DEBUG=1
make build # Build Go server
make proto # Regenerate protobuf
make test # Run tests + consistency checks
make restart # Kill, rebuild, restart server
make clean # Clean build artifacts
Install test dependencies:
pip3 install -r requirements-test.txt
Run tests:
make test # All tests
pytest tests/ -v # Python tests only
go test ./... # Go tests only
Use MCP Inspector:
make run # Start server
make inspector # Launch inspector at http://localhost:5173
ida-headless-mcp/
├── cmd/ida-mcp-server/ # Go MCP server entry point
├── internal/
│ ├── server/ # MCP tool handlers
│ ├── session/ # Session registry
│ └── worker/ # Worker process manager
├── proto/ # Protobuf definitions
├── python/worker/ # Python worker (idalib wrapper)
├── contrib/il2cpp/ # Il2CppDumper helpers (MIT)
└── tests/ # Test suites
proto/ida/worker/v1/ida_service.protomake protopython/worker/ida_wrapper.pypython/worker/connect_server.pyinternal/server/server.goopen_binary(path)/tmp/ida-worker-{id}.sockclose_binary: save database, kill worker, cleanup<database_directory>/sessions for automatic restoration after server restartWorker fails to start:
python3 -c "import idapro; print('OK')"
If this fails, run ./scripts/setup_idalib.sh
Socket timeout: Check Python worker logs. Worker may have crashed during init.
Port already in use:
lsof -ti:17300 | xargs kill
# or use a different port
./bin/ida-mcp-server --port 17301
Session not found:
Session may have timed out. Use list_sessions to check active sessions.
MIT
MCP Servers:
Metadata Dumpers:
import_il2cpp)import_flutter)Добавь это в claude_desktop_config.json и перезапусти Claude Desktop.
{
"mcpServers": {
"zboralski-ida-headless-mcp": {
"command": "npx",
"args": []
}
}
}