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

1. IDA Pro 9.0+ or IDA Essential 9.2+

2. idalib: install and activate:

   ./scripts/setup_idalib.sh
   

   See IDA as a Library documentation.

3. Go 1.21+ with protoc tools:

   make install-tools
   

4. Python 3.10+ with dependencies:

   pip3 install -r python/requirements.txt
   

5. Optional: Il2CppDumper for Unity game analysis

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

... View full README on GitHub