Ida Headless MCP

1 hour ago 2

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:

Multi-session concurrency via process isolation
52 MCP tools for binary analysis
Il2CppDumper and Blutter metadata import support

IDA Pro 9.0+ or IDA Essential 9.2+
idalib - Install and activate:

./scripts/setup_idalib.sh

See IDA as a Library documentation.
Go 1.21+ with protoc tools:
Python 3.10+ with Connect:

pip3 install connect-python
Optional: Il2CppDumper for Unity game analysis
Optional: Blutter for Flutter/Dart app analysis

git clone <repo-url> cd ida-headless-mcp ./scripts/setup_idalib.sh make install-tools make build

Server exposes both transports on port 17300 (configurable via config.json, env, or --port):

Streamable HTTP (recommended): http://localhost:17300/
SSE compatibility endpoint: http://localhost:17300/sse

Edit ~/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 51 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}

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 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

Add RPC to proto/ida/worker/v1/ida_service.proto
Regenerate: make proto
Implement in python/worker/ida_wrapper.py
Add handler in python/worker/connect_server.py
Register MCP tool in internal/server/server.go

Client calls open_binary(path)
Go creates session in registry (UUID)
Go spawns Python worker subprocess
Worker creates Unix socket at /tmp/ida-worker-{id}.sock
Worker opens IDA database with idalib
Go creates Connect RPC clients over socket
Subsequent tool calls proxy to worker via Connect
Watchdog monitors idle time (default: 4 hours)
On timeout or close_binary: save database, kill worker, cleanup
Session metadata persists under <database_directory>/sessions for automatic restoration after server restart

Worker fails to start:

python3 -c "import idapro; print('OK')"

If 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 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: