无头IDA-MCP服务器

Name: 无头IDA-MCP服务器
Author: zboralski

作者：zboralski17 星标更新：2025-11-13

安装使用来源：spider==github.com

项目介绍

IDA Headless MCP Server

通过Model Context Protocol进行无头IDA Pro二进制分析。Go负责多会话并发管理，而Python工作者处理IDA操作。

架构

┌─────────────────┐
│  MCP客户端     │  Claude桌面版，Claude代码编辑器，CLI
│  (HTTP/SSE)     │
└────────┬────────┘
         │ http://localhost:17300/
         ▼
┌─────────────────┐
│   Go服务器     │  会话注册表，工作者管理器，看门狗
│   (MCP工具)   │
└────────┬────────┘
         │ 通过Unix套接字连接RPC
         ▼
┌─────────────────┐
│ Python工作者   │  IDA + idalib（每个会话一个）
│ (每个会话)   │
└─────────────────┘

关键特性：

通过进程隔离实现多会话并发
提供52个MCP工具用于二进制分析
支持Il2CppDumper和Blutter元数据导入

预备条件

IDA Pro 9.0+ 或 IDA Essential 9.2+
idalib - 安装并激活：
```
./scripts/setup_idalib.sh
```
查看IDA作为库的文档。
Go 1.21+ 带有protoc工具：
```
make install-tools
```
Python 3.10+ 带有Connect：
```
pip3 install connect-python
```
可选：Il2CppDumper 用于Unity游戏分析
可选：Blutter 用于Flutter/Dart应用分析

安装

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

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

使用

启动服务器

./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)
   → {伪代码...}

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 Inspector：

make run            # 启动服务器
make inspector      # 在http://localhost:5173启动inspector

项目结构

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

会话生命周期

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