Ida Headless MCP

🚀 IDA Headless MCP Server

モデルコンテキストプロトコルを介して、IDA Proによるヘッドレスなバイナリ解析を行います。Goが複数セッションの並行処理をオーケストレーションし、PythonワーカーがIDAの操作を担当します。

✨ 主な機能

• プロセス分離による複数セッションの並行処理
• バイナリ解析用の52種類のMCPツール
• Il2CppDumper と Blutter のメタデータインポートサポート

📦 インストール

前提条件

1. IDA Pro 9.0以上 または IDA Essential 9.2以上
2. idalib - インストールとアクティベート:

   ./scripts/setup_idalib.sh
   

   IDA as a Library documentation を参照してください。
3. Go 1.21以上 とprotocツール:

   make install-tools
   

4. Python 3.10以上 と依存関係:

   pip3 install -r python/requirements.txt
   

5. オプション: Il2CppDumper - Unityゲーム解析用
6. オプション: Blutter - Flutter/Dartアプリ解析用

インストール手順

git clone <repo-url>
cd ida-headless-mcp
make setup

これにより、idalibのセットアップ、Pythonの依存関係のインストール、サーバーのビルドが行われます。

手動でのセットアップやトラブルシューティングの場合は:

./scripts/setup_idalib.sh   # idalibのセットアップ (IDA Pro/Essential 9.xが必要)
make install-python         # Pythonの依存関係のインストール
make build                  # Goサーバーのビルド

💻 使用例

サーバーの起動

./bin/ida-mcp-server

サーバーはポート17300で2種類のトランスポートを公開します (config.json、環境変数、または --port で設定可能):

• ストリーミング可能なHTTP (推奨): http://localhost:17300/
• SSE互換エンドポイント: http://localhost:17300/sse

Claude Desktopの設定

~/Library/Application Support/Claude/claude_desktop_config.json を編集します:

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

編集後、Claude Desktopを再起動してください。

Claude Codeの設定

.claude/settings.json を ~/.claude/settings.json にコピーすると、51種類のIDA MCPツールすべてにアクセスできます。

基本的なワークフロー

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}

MCPを介して tools/list を使用すると、利用可能なすべてのツールを確認できます。

📚 ドキュメント

コマンドラインフラグ

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

環境変数 (CLIフラグによって上書きされます)

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

開発

ビルド

make build          # Goサーバーのビルド
make proto          # Protobufの再生成
make test           # テストと整合性チェックの実行
make clean          # ビルドアーティファクトのクリーンアップ

テスト

テスト用の依存関係をインストール:

pip3 install -r requirements-test.txt

テストを実行:

make test           # すべてのテスト
pytest tests/ -v    # Pythonテストのみ
go test ./...       # Goテストのみ

インタラクティブテスト

MCPインスペクターを使用:

make run            # サーバーの起動
make inspector      # http://localhost:5173でインスペクターを起動

プロジェクト構造

ida-headless-mcp/
├── cmd/ida-mcp-server/   # Go MCPサーバーのエントリーポイント
├── internal/
│   ├── server/           # MCPツールハンドラー
│   ├── session/          # セッションレジストリ
│   └── worker/           # ワーカープロセスマネージャー
├── proto/                # Protobuf定義
├── python/worker/        # Pythonワーカー (idalibラッパー)
├── contrib/il2cpp/       # Il2CppDumperヘルパー (MIT)
└── tests/                # テストスイート

新しいツールの追加

1. proto/ida/worker/v1/ida_service.proto にRPCを追加する
2. make proto で再生成する
3. python/worker/ida_wrapper.py で実装する
4. python/worker/connect_server.py にハンドラーを追加する
5. internal/server/server.go でMCPツールを登録する

セッションのライフサイクル

1. クライアントが open_binary(path) を呼び出す
2. Goがレジストリにセッションを作成する (UUID)
3. GoがPythonワーカーのサブプロセスを起動する
4. ワーカーが /tmp/ida-worker-{id}.sock にUnixソケットを作成する
5. ワーカーがidalibを使ってIDAデータベースを開く
6. Goがソケットを介してConnect RPCクライアントを作成する
7. それ以降のツール呼び出しはConnectを介してワーカーにプロキシされる
8. ウォッチドッグがアイドル時間を監視する (デフォルト: 4時間)
9. タイムアウトまたは close_binary で: データベースを保存し、ワーカーを終了し、クリーンアップする
10. セッションメタデータは <database_directory>/sessions の下に保存され、サーバー再起動後に自動的に復元されます

トラブルシューティング

ワーカーが起動しない場合:

python3 -c "import idapro; print('OK')"

失敗した場合は、./scripts/setup_idalib.sh を実行してください。

ソケットタイムアウトの場合: Pythonワーカーのログを確認してください。ワーカーが初期化中にクラッシュしている可能性があります。

ポートが既に使用されている場合:

lsof -ti:17300 | xargs kill
# または別のポートを使用する
./bin/ida-mcp-server --port 17301

セッションが見つからない場合: セッションがタイムアウトしている可能性があります。list_sessions を使用してアクティブなセッションを確認してください。

📄 ライセンス

MIT

関連プロジェクト

MCPサーバー

• LaurieWired/GhidraMCP - Ghidra MCPサーバー
• mrexodia/ida-pro-mcp - SSEトランスポートを持つIDA Pro MCP
• cnitlrt/headless-ida-mcp-server - 別のヘッドレスIDA MCP

メタデータダンパー

• Perfare/Il2CppDumper - Unity Il2Cppメタデータ抽出 (import_il2cppで使用)
• worawit/blutter - Flutter/Dartのリバースエンジニアリング (import_flutterで使用)

参考資料

• MCP Specification
• Connect RPC
• IDA Pro idalib