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
• Il2CppDumper and Blutter metadata import support

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

   pip3 install connect-python
   

5. Optional: Il2CppDumper for Unity game analysis

6. Optional: Blutter for Flutter/Dart app analysis

Installation

git clone 
cd ida-headless-mcp

./scripts/setup_idalib.sh
make install-tools
make build

Usage

Start Server

./bin/ida-mcp-server

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

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

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