IDA Headless MCP Server

Headless IDA Pro binary analysis via Model Context Protocol. Go orchestrates multi-session concurrency while Python workers handle IDA operations.

Architecture

┌─────────────────┐
│  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
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

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:

   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

Installation

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

Usage

Start Server

./bin/ida-mcp-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:

{
  "mcpServers": {
    "ida-headless": {
      "url": "http://127.0.0.1:17300/",
      "type": "http"
    }
  }
}

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

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}

Flutter/Dart Import

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.

Configuration

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

Development

Build

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

Testing

Install test dependencies: ``bash pip3 install -r requirements-test.txt ``

Run tests: ``bash make test # All tests pytest tests/ -v # Python tests only go test ./... # Go tests only ``

Interactive Testing

Use MCP Inspector: ``bash make run # Start server make inspector # Launch inspector at http://localhost:5173 ``

Project Structure

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

Adding New Tools

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

Session Lifecycle

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

Troubleshooting

Worker fails to start: ``bash 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: ```bash 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.

License

MIT

Related Projects

MCP Servers:

Metadata Dumpers:

Perfare/Il2CppDumper (used by import_il2cpp)
zboralski/unflutter (used by import_flutter)

ida-headless-mcp