Ida Headless MCP

🚀 IDA無頭MCP服務器

IDA無頭MCP服務器可通過模型上下文協議（MCP）實現IDA Pro的無頭二進制分析。藉助Go語言實現多會話併發管理，同時利用Python工作進程處理IDA操作。

🚀 快速開始

前提條件

1. IDA Pro 9.0及以上版本或IDA Essential 9.2及以上版本
2. idalib - 安裝並激活：

   ./scripts/setup_idalib.sh
   

   詳情請參考 IDA作為庫的文檔。
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上提供兩種傳輸方式（可通過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 查看所有可用工具。

✨ 主要特性

• 通過進程隔離實現多會話併發
• 提供52個用於二進制分析的MCP工具
• 支持導入 Il2CppDumper 和 Blutter 的元數據

🔧 技術細節

架構

┌─────────────────┐
│  MCP Client     │  Claude Desktop, Claude Code, CLI
│  (HTTP/SSE)     │
└────────┬────────┘
         │ http://localhost:17300/
         ▼
┌─────────────────┐
│   Go Server     │  會話註冊表、工作進程管理器、看門狗
│   (MCP Tools)   │
└────────┬────────┘
         │ 通過Unix套接字進行RPC連接
         ▼
┌─────────────────┐
│ Python Worker   │  IDA + idalib（每個會話一個）
│ (per session)   │
└─────────────────┘

會話生命週期

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 下，以便服務器重啟後自動恢復

📚 詳細文檔

配置

命令行參數

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

環境變量（會被命令行參數覆蓋）

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工具

🛠️ 故障排除

工作進程啟動失敗

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規範
• Connect RPC
• IDA Pro idalib