JinDaGe - ida-headless-mcp MCP Details

article

README

🚀 IDA无头MCP服务器

IDA无头MCP服务器可通过模型上下文协议（MCP）实现IDA Pro的无头二进制分析。借助Go语言实现多会话并发管理，同时利用Python工作进程处理IDA操作。

🚀 快速开始

前提条件

IDA Pro 9.0及以上版本或IDA Essential 9.2及以上版本
idalib - 安装并激活：
```
./scripts/setup_idalib.sh
```
详情请参考 IDA作为库的文档。
Go 1.21及以上版本 并安装protoc工具：
```
make install-tools
```
Python 3.10及以上版本 并安装依赖：
```
pip3 install -r python/requirements.txt
```
可选：Il2CppDumper 用于Unity游戏分析
可选：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)   │
└─────────────────┘

会话生命周期

客户端调用 open_binary(path)
Go服务器在注册表中创建会话（使用UUID）
Go服务器启动Python工作进程子进程
工作进程在 /tmp/ida-worker-{id}.sock 创建Unix套接字
工作进程使用idalib打开IDA数据库
Go服务器通过套接字创建Connect RPC客户端
后续的工具调用通过Connect代理到工作进程
看门狗监控空闲时间（默认：4小时）
超时或调用 close_binary 时：保存数据库，终止工作进程，清理资源
会话元数据保存在 <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/                # 测试套件

添加新工具

在 proto/ida/worker/v1/ida_service.proto 中添加RPC
重新生成：make proto
在 python/worker/ida_wrapper.py 中实现
在 python/worker/connect_server.py 中添加处理程序
在 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使用）

ida-headless-mcp