IDA MCP Server 使用说明

支持多文件、多会话并行分析。

支持平台

• ✅ Windows (10/11)
• ✅ macOS (12+)
• ✅ Linux (Ubuntu 20.04+, Debian 11+)

---

快速开始

1. 环境要求

2. 安装步骤

Windows

# 安装 uv
pip install uv

# 进入项目目录
cd ida-pro-mcp

# 安装依赖
uv sync

macOS

# 方式一：使用官方脚本安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 方式二：使用 Homebrew
brew install uv

# 进入项目目录
cd ida-pro-mcp

# 安装依赖
uv sync

Linux

# 使用官方脚本安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 进入项目目录
cd ida-pro-mcp

# 安装依赖
uv sync

3. 配置文件（推荐）

编辑根目录 config.toml，相对路径相对于该文件解析：

port = 8745                  # MCP 主端口
host = "127.0.0.1"           # 监听地址
base_session_port = 10000    # 会话起始端口
max_sessions = 10            # 最大会话数量
file_load_timeout = 3600     # 文件加载初始化超时（秒）
analyze_dir = "analyze"      # 预加载的 PE/ELF/Mach-O 目录
ida_dir = ""                 # 可选，IDA 安装路径；留空则使用环境变量 IDADIR
uv = "uv"                    # uv 可执行文件
skip_port_check = false      # 跳过端口检查
no_preload = false           # 不预载文件，空启动
mcp_dir = "ida-pro-mcp"      # ida-pro-mcp 项目路径

各平台 IDA 路径配置示例

# Windows
ida_dir = "C:/Program Files/IDA Pro 9.2"

# macOS
ida_dir = "/Applications/IDA Pro 9.2/ida.app/Contents/MacOS"

# Linux
ida_dir = "/opt/ida-9.2"

配置来源：config.toml > 内置默认

说明：若 config.toml 中未设置 ida_dir，则会沿用当前环境中的 IDADIR。

---

4. 使用方式

方式一：跨平台一键启动（推荐）

基于 config.toml 的配置，自动扫描 analyze/ 下的二进制文件并启动：

# Windows / macOS / Linux 通用
python start.py

除 --config 外，运行参数全部从 config.toml 读取。

如需修改端口、会话数、超时、分析目录、IDA 路径等，请直接编辑 config.toml。

启动前，start.py 会尝试清理主端口和会话端口范围上的旧进程。

方式二：手动创建会话

1. 在 config.toml 中设置 no_preload = true 后运行 python start.py 启动空服务器
2. 通过 MCP 调用 session_create 创建分析会话

---

MCP 配置

Claude Code

claude mcp add --transport http idamcp --scope project http://127.0.0.1:8745/mcp

Claude Desktop

配置文件位置：

配置内容：

{
  "mcpServers": {
    "ida-auto": {
      "transport": {
        "type": "http",
        "url": "http://127.0.0.1:8745/mcp"
      }
    }
  }
}

Cherry Studio

{
  "mcpServers": {
    "ida-auto": {
      "name": "IDA MCP 服务器",
      "baseUrl": "http://127.0.0.1:8745/mcp",
      "type": "http"
    }
  }
}

---

可用工具

会话管理工具

分析工具

当前版本提供多类分析工具，包含反编译、反汇编、搜索、导出、调试、类型与内存操作等能力。下面是部分类别示例：

---

使用示例

创建会话并分析

1. session_list - 查看所有会话
2. session_switch - 切换到目标会话
3. lookup_funcs - 查找 main 函数
4. decompile - 反编译 main 函数

参数示例

// 查找函数
{"name": "lookup_funcs", "arguments": {"queries": "main"}}

// 反编译
{"name": "decompile", "arguments": {"addrs": ["0x140001440"]}}

// 列出函数
{"name": "list_funcs", "arguments": {"queries": {"count": 10, "offset": 0}}}

---

故障排除

端口被占用

Windows

# 查看端口占用
netstat -ano | findstr ":8745"

# 终止进程
taskkill /F /PID 

macOS / Linux

# 查看端口占用
lsof -i :8745

# 终止进程
kill -9 

# 或使用一条命令
lsof -ti :8745 | xargs kill -9

IDB 文件被锁定

删除 analyze/ 文件夹中的 .id0, .id1, .id2, .i64 等文件，重新分析。

会话创建失败

1. 检查 IDA 路径是否正确
2. 确认 IDA 版本 >= 9.2
3. 查看服务器日志输出
4. 确认 Python 版本 >= 3.11

macOS 特定问题

# 如果遇到权限问题
chmod +x start.py

# 如果 uv 命令找不到
# 方式一：添加到 PATH
export PATH="$HOME/.cargo/bin:$PATH"

# 方式二：使用完整路径
~/Downloads/ida-pro-mcp/idb/python.exe -m uv sync

Linux 特定问题

# 如果缺少依赖
sudo apt install python3-dev build-essential

# 如果遇到 Python 找不到的问题
which python3
python3 --version

---

目录结构

IDA-MCP-Release/
├── analyze/               # 放待分析的二进制文件
│   ├── *.exe             # Windows PE 文件
│   ├── *.elf / *_elf     # Linux ELF 文件
│   └── *.bin / *_macho   # macOS Mach-O 文件
├── ida-pro-mcp/          # MCP 服务器核心
│   ├── .venv/           # 虚拟环境
│   └── src/
├── start.py              # 跨平台一键启动脚本
└── config.toml           # 配置文件

---

技术信息

---

更新日志

v2.0.1 (2026-04-06)

• ✅ 修复会话端口 TIME_WAIT 后无法重绑（allow_reuse_address）
• ✅ 修复多会话代理超时对齐（50s proxy timeout，小于客户端 ~60s）
• ✅ 修复 IDA session worker 线程模型（单线程 HTTPServer + execute_sync 兼容）
• ✅ 多会话代理使用线程化 HTTP 服务器，支持并发客户端请求
• ✅ 移除 multiserver 中无用的 _register_session_tools / _register_proxy_tools

v2.0.0 (2026-04-05)

• ✅ 修复工具加载问题
• ✅ 修复会话进程生命周期（使用 blocking 模式）
• ✅ 分析工具链路可用
• ✅ 添加跨平台支持（Windows/macOS/Linux）
• ✅ 改进错误处理和日志输出

---

许可证

本项目基于 MIT 许可证开源。