IDA Headless MCP Server
Headless IDA Pro binary analysis via Model Context Protocol. Go orchestrates multi-session concurrency while Python workers handle IDA operations.
Quick start
The easiest path is to install the plugin, let the MCP client start it over stdio, then run the one-time idalib setup. The repository keeps a root plugin package for direct/manual use and a Codex marketplace package at plugins/ida-headless-mcp/. Go/Python source code and development-only files live under src/. Go is only required if you build from source.
Install as a Claude Code plugin
/plugin marketplace add killaragorn/ida-headless-mcp
/plugin install ida-headless-mcp@ida-headless-mcp
Initialize IDA's Python library once per machine:
/ida-init
/ida-status
/mcp
/ida-init detects IDA, installs the idapro Python package, and installs Python worker dependencies. It uses the bundled binary and does not rebuild it by default. Requirements: Python 3.10+ and IDA Pro 9.0+ or IDA Essential 9.2+.
Install as a Codex plugin (marketplace)
codex plugin marketplace add killaragorn/ida-headless-mcp
codex plugin add ida-headless-mcp@ida-headless-mcp
Restart or refresh Codex if the new MCP server is not visible immediately. The marketplace entry points at plugins/ida-headless-mcp/, whose manifest declares an ida-headless stdio MCP server that runs python ./scripts/launch.py --stdio.
Finish the one-time idalib setup from the plugin directory, or ask Codex to use the bundled ida-init skill:
cd ida-headless-mcp
python scripts/launch.py init --skip-build
Check setup with the bundled status skill or manually:
python scripts/launch.py version
codex mcp list
Install for Codex CLI without the marketplace
If you'd rather skip the marketplace and register the server directly:
git clone https://github.com/killaragorn/ida-headless-mcp.git
cd ida-headless-mcp
python scripts/launch.py init --skip-build
python scripts/launch.py print-config codex-add
Run the printed codex mcp add ... command. It points Codex at the plugin package's platform-specific prebuilt binary, for example bin/ida-mcp-server-windows-amd64.exe on Windows.
Print client snippets at any time with:
python scripts/launch.py print-config claude-desktop
python scripts/launch.py print-config claude-code
python scripts/launch.py print-config codex
python scripts/launch.py print-config codex-add
Use as a standalone HTTP server
Run python scripts/launch.py with no flags to start the plugin's prebuilt HTTP server. It listens on http://localhost:17300/ (Streamable HTTP) and http://localhost:17300/sse (SSE). See Standalone HTTP server below for client config.
Architecture
┌─────────────────┐
│ MCP Client │ Claude Desktop, Claude Code, Codex CLI
│ (stdio/HTTP) │
└────────┬────────┘
│ stdio or http://localhost:17300/
▼
┌─────────────────┐
│ Go Server │ Session registry, worker manager, watchdog
│ (MCP Tools) │
└────────┬────────┘
│ Connect RPC over TCP loopback
▼
┌─────────────────┐
│ 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
For plugin users:
- IDA Pro 9.0+ or IDA Essential 9.2+
- Python 3.10+ available as
python or python3
- Run
ida-init once to install/activate idalib and Python worker dependencies.
For source builds and development, also install Go 1.21+. Protobuf tools are only needed when regenerating protobuf code:
cd src
make install-tools
Optional metadata import helpers:
git clone https://github.com/zboralski/unflutter.git
cd unflutter && make install
Source build
git clone <repo-url>
cd ida-headless-mcp
cd src
make setup
This runs idalib setup, installs Python dependencies, and builds a source-tree src/bin/ida-mcp-server.
For manual setup or troubleshooting:
cd src
./scripts/setup_idalib.sh # Setup idalib (requires IDA Pro/Essential 9.x)
make install-python # Install Python dependencies
make build # Build Go server
Standalone HTTP server
python scripts/launch.py
