home / mcp / ida headless mcp server

IDA Headless MCP Server

Headless IDA Pro binary analysis via Model Context Protocol with multi-session concurrency and Python workers.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "zboralski-ida-headless-mcp": {
      "url": "http://127.0.0.1:17300/",
      "headers": {
        "IDA_MCP_PORT": "17300",
        "IDA_MCP_DEBUG": "1",
        "IDA_MCP_WORKER": "/custom/worker.py",
        "IDA_MCP_MAX_SESSIONS": "10",
        "IDA_MCP_SESSION_TIMEOUT_MIN": "240"
      }
    }
  }
}

You can analyze binaries with headless IDA Pro using the Model Context Protocol. This MCP server runs multiple analysis sessions concurrently, each in isolation, orchestrated by Go with Python workers handling the actual IDA operations. It enables scalable, scriptable binary analysis from your IDEs or command line clients.

How to use

Start the MCP server and connect your client over HTTP to the local MCP endpoint. You can open a binary for analysis, create a session, run automated analysis, inspect entry points and decompiled code, and finally close the session to clean up resources. Each session runs IDA in its own worker process, so multiple binaries can be analyzed in parallel without interference. Use the standard client tools to list active sessions, open new binaries, and invoke analysis tools across sessions.

How to install

Prerequisites and step-by-step setup to run the headless MCP server.

# Prerequisites
# 1) IDA Pro 9.0+ or IDA Essential 9.2+

# 2) idalib - install and activate
./scripts/setup_idalib.sh

# 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 steps
git clone <repo-url>
cd ida-headless-mcp

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

Configuration and startup

Configure the server to listen on port 17300 (default) and start it using the recommended flags. You can customize port, session limits, and worker behavior through CLI options or environment variables as shown.

./bin/ida-mcp-server \
  --port 17300 \
  --max-sessions 10 \
  --session-timeout 4h \
  --worker python/worker/server.py \
  --debug

Client configuration

Point your MCP-enabled clients at the local server endpoint to enable HTTP transport or SSE compatibility. For Claude Desktop and Claude Code, set the MCP server URL to the local host address and port.

{
  "mcpServers": {
    "ida_headless": {
      "url": "http://127.0.0.1:17300/",
      "type": "http"
    }
  }
}