IDA Pro MCP 插件（Python 3.9 兼容版）

基于 namename333/idapromcp_333 修复，解决了依赖安装和 Python 兼容性问题。

兼容性

组件	版本
IDA Pro	7.x - 8.x (测试于 8.4)
IDA Python	3.9+
MCP Server Python	3.11+

简介

通过 MCP (Model Context Protocol) 将 LLM 客户端连接到 IDA Pro，实现：

函数/变量自动重命名和类型推断
混淆检测和反调试识别
算法识别（RC4、AES、Base64等）
批量分析和报告导出
支持 Cursor、Windsurf、Claude Desktop 等客户端

修复内容

本版本修复了原项目的以下问题：

添加缺失的 requirements.txt
修复 Python 3.9 兼容性（原版要求 3.11+）
- 添加 from __future__ import annotations
- 使用 typing_extensions.NotRequired
- 修复 TypedDict/Generic 继承问题
修正依赖版本冲突（typing-inspection 0.9.0 → 0.4.0）
采用独立 Python 环境，避免破坏 IDA Pro

功能特性

基于原版 mrexodia/ida-pro-mcp，由 namename333/idapromcp_333 增强。

核心功能

自动化分析：一句 prompt 完成函数/变量重命名、类型修复、注释、结构体声明
多客户端支持：Cursor、Cline、Roo Code、Windsurf、Claude Desktop、LM Studio
批量处理：批量重命名、注释、类型修复、patch 点定位

增强功能（namename333 版本）

混淆检测增强：
- 控制流平坦化（flattening）
- switch/case 混淆
- 间接跳转
- 死代码（dead_code）
- 字符串加密（string_encryption）
- 反调试检测（anti_debug）：TLS、PEB、int 0x2d 等
算法识别增强：
- 加密算法：RC4、AES、DES、TEA
- 哈希算法：MD5、SHA1、SHA256、CRC32
- 编码算法：Base64、Base32/58/85、ROT13、XOR
- 压缩算法：Zlib、LZMA
- 其他：Mersenne Twister（随机数生成）
- 提供算法类型和置信度
报告生成：
- Markdown 格式多维度分析报告
- 包含入口点、关键函数、反调试点、算法、混淆特征
- 主流程图、代码复杂度、交叉引用热点
动态分析：
- 生成 angr/frida 脚本
- 符号执行、动态 hook
- 寄存器/内存监控
其他：
- 流程图可视化（mermaid/graphviz）
- 增量变更追踪
- 全中文注释

架构说明

采用双 Python 环境，避免版本冲突：

IDA Pro 插件：使用 IDA 自带的 Python 3.9，监听 127.0.0.1:13337
MCP 服务器：使用独立的 Python 3.12，通过 HTTP 连接插件

注意：不要切换 IDA Pro 的 Python 版本，否则可能导致 IDA 无法启动。

安装

环境要求

IDA Pro 7.x - 8.x
系统安装 Python 3.12（独立于 IDA Pro）
macOS / Windows / Linux

快速安装

完整安装命令（3 步）

# 1. 克隆项目
git clone https://github.com/cybermaxluo/IDAProMCP_Max.git
cd IDAProMCP_Max/

# 2. 安装依赖（使用独立 Python 3.12，不是 IDA Pro 的 Python）
# 将下面的路径替换为您系统的实际 Python 3.12 路径

# macOS (Miniconda) 示例
/opt/miniconda3/bin/python3.12 -m pip install -r requirements.txt
/opt/miniconda3/bin/python3.12 -m pip install -e .

# macOS (Homebrew) 示例
/usr/local/bin/python3.12 -m pip install -r requirements.txt
/usr/local/bin/python3.12 -m pip install -e .

# Windows
C:\Python312\python.exe -m pip install -r requirements.txt
C:\Python312\python.exe -m pip install -e .

# Linux
/usr/bin/python3.12 -m pip install -r requirements.txt
/usr/bin/python3.12 -m pip install -e .

# 3. 安装 IDA Pro 插件和 LLM 客户端配置
# macOS 示例（替换为您的实际路径）
/opt/miniconda3/bin/python3.12 -m ida_pro_mcp.server --install

# Windows
C:\Python312\python.exe -m ida_pro_mcp.server --install

# Linux
/usr/bin/python3.12 -m ida_pro_mcp.server --install

这会自动完成：

✅ 安装插件到 ~/.idapro/plugins/mcp-plugin.py
✅ 配置 Cursor (~/.cursor/mcp.json)
✅ 配置 Claude Desktop
✅ 配置 Windsurf
✅ 配置 Claude Code

使用自动安装脚本（macOS）

# 或者使用一键安装脚本（需要先编辑脚本中的 Python 路径）
chmod +x install.sh
./install.sh

步骤 3: 配置 LLM 客户端

安装后会自动生成配置文件，或手动创建：

macOS 示例 (~/.cursor/mcp.json):

{
  "mcpServers": {
    "ida-pro-mcp": {
      "command": "python3.12",
      "args": ["-m", "ida_pro_mcp.server"],
      "timeout": 1800,
      "disabled": false
    }
  }
}

注：将 python3.12 替换为您系统的完整路径，如 /opt/miniconda3/bin/python3.12

Windows 示例:

{
  "mcpServers": {
    "ida-pro-mcp": {
      "command": "C:\\Python312\\python.exe",
      "args": [
        "-m",
        "ida_pro_mcp.server"
      ],
      "timeout": 1800,
      "disabled": false
    }
  }
}

3. 验证安装

方法 1: 使用自动测试脚本（推荐）⭐

cd ~/tools/idapromcp_333
python3 test_plugin.py

预期输出：

🧪 IDA Pro MCP 插件测试套件
✅ 通过: 语法检查
✅ 通过: 模块导入
✅ 通过: Python 版本
✅ 通过: MCP 服务器
总计: 4/4 测试通过
🎉 所有测试通过！

方法 2: 手动检查

# 检查依赖是否安装成功（使用独立 Python）
/opt/miniconda3/bin/python3.12 -c "import mcp; print(f'MCP version: {mcp.__version__}')"

# 检查 IDA 插件是否安装
# macOS
ls -la ~/.idapro/plugins/mcp-plugin.py

# Windows
dir "%APPDATA%\Hex-Rays\IDA Pro\plugins\mcp-plugin.py"

# 测试插件语法（Python 3.9）
/Library/Developer/CommandLineTools/Library/Frameworks/Python3.framework/Versions/3.9/bin/python3 -m py_compile ~/.idapro/plugins/mcp-plugin.py

🚀 使用方法

工作原理

┌─────────────────┐         ┌──────────────────┐         ┌─────────────┐
│  LLM 客户端      │         │  MCP 服务器       │         │  IDA Pro    │
│  (Cursor/Cline) │ ◄─────► │  (Python 3.12)   │ ◄─────► │  插件(3.9)  │
└─────────────────┘  stdio  └──────────────────┘  HTTP   └─────────────┘
                                                   :13337

LLM 客户端启动 MCP 服务器（Python 3.12）
你在 IDA Pro 中启动 MCP 插件（Python 3.9）
MCP 服务器通过 HTTP 连接到 IDA Pro 插件
两者协同工作，互不干扰

启动步骤

步骤 1: 启动 IDA Pro 和插件

打开 IDA Pro
加载目标二进制文件
按 Ctrl+Alt+M（macOS: Ctrl+Option+M）
或通过菜单 Edit -> Plugins -> MCP

你应该会看到：

[MCP] 服务器已启动: http://127.0.0.1:13337

步骤 2: 在 LLM 客户端中使用

打开 Cursor/Cline 等客户端，输入指令：

请连接到 IDA Pro 并获取当前分析的二进制文件信息

MCP 服务器会自动连接到 IDA Pro 的插件（端口 13337）并执行操作。

📋 使用示例

基础操作

# 检查连接
请检查 IDA Pro 连接状态

# 获取元数据
获取当前 IDB 的基本信息

# 列出函数
列出前 100 个函数

高级分析

# 函数分析
分析函数 sub_401000，包括：
1. 参数和返回值分析
2. 控制流程说明
3. 算法识别
4. 混淆和反调试检测

# 批量重命名
对所有 sub_ 开头的函数进行智能重命名

# 生成报告
生成完整的结构化分析报告

混淆检测

# 检测单个函数
检测函数 sub_401234 的混淆特征

# 全局扫描
扫描所有函数，找出使用混淆的函数列表

算法识别

# 识别加密算法
分析函数 sub_405000，识别使用的加密算法

# 批量识别
对所有函数进行算法特征扫描

🐛 常见问题

Q1: IDA Pro 无法启动

可能原因：Python 版本被错误切换

解决方法：

# 恢复到 Python 3.9
cd "/Applications/IDA Pro 8.4/ida64.app/Contents/MacOS"
./idapyswitch -s /Library/Developer/CommandLineTools/Library/Frameworks/Python3.framework/Versions/3.9/Python3

Q2: 提示 "无法连接到 IDA Pro"

检查清单：

✅ IDA Pro 是否已启动
✅ 是否已按 Ctrl+Alt+M 启动插件
✅ 端口 13337 是否被占用
✅ IDA Pro 输出窗口是否有错误信息

调试方法：

# 查看端口是否监听
lsof -i :13337

# 测试连接
curl http://127.0.0.1:13337/mcp

Q3: 安装时提示 "No matching distribution found for mcp>=1.6.0"

原因：使用了 Python 3.9 安装依赖

解决方法：

# 必须使用 Python 3.11+ 安装 MCP 依赖
/opt/miniconda3/bin/python3.12 -m pip install -r requirements.txt

# 不要使用 IDA Pro 的 Python 3.9

Q4: typing-inspection 版本错误

已在本版本中修复，使用 typing-inspection>=0.4.0

Q5: 没有找到 Python 3.12

安装 Python 3.12：

macOS (Homebrew):

brew install python@3.12

macOS (Miniconda):

curl -O https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh
bash Miniconda3-latest-MacOSX-arm64.sh

Windows:

下载：https://www.python.org/downloads/
安装时勾选 "Add Python to PATH"

Linux (Ubuntu/Debian):

sudo apt update
sudo apt install python3.12 python3.12-pip

Q6: LLM 客户端配置文件在哪里

客户端	配置文件路径 (macOS)
Cursor	`~/.cursor/mcp.json`
Cline	VSCode 扩展设置
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windsurf	`~/.codeium/windsurf/mcp_config.json`
Claude Code	`~/.claude.json`

Windows 路径将 ~ 替换为 %USERPROFILE%

📁 项目结构

idapromcp_333/
├── 📄 README.md                   # 主文档（本文档）
├── 📄 CHANGELOG.md                # 详细更新日志
├── 📄 TESTING.md                  # 测试指南
├── 📄 SUMMARY.md                  # 修复总结
├── 🧪 test_plugin.py              # 自动测试脚本 ⭐
├── 🔧 install.sh                  # 自动安装脚本
├── 📦 requirements.txt            # Python 依赖（修复版）
├── 📄 pyproject.toml              # 项目配置
├── 📁 src/
│   └── ida_pro_mcp/
│       ├── __init__.py
│       ├── server.py              # MCP 服务器（Python 3.12）
│       ├── idalib_server.py       # IDALib 服务器（独立模式）
│       └── mcp-plugin.py          # ✅ IDA Pro 插件（Python 3.9 兼容）
├── 📁 build/                      # 构建输出
└── 📄 LICENSE                     # MIT 协议

⚙️ 高级配置

命令行参数

python -m ida_pro_mcp.server [options]

选项：
  --install              安装 MCP 服务器和 IDA 插件
  --uninstall            卸载 MCP 服务器和 IDA 插件
  --transport PROTOCOL   指定通信协议 (stdio | http://host:port)
  --ida-rpc URL          指定 IDA RPC 服务器地址 (默认: http://127.0.0.1:13337)
  --unsafe               启用不安全函数（调试器操作等）
  --config               生成 MCP 配置 JSON

环境变量

export IDA_HOST="127.0.0.1"
export IDA_PORT="13337"
export MCP_LOG_LEVEL="DEBUG"

自定义端口

如果端口 13337 被占用：

修改 IDA 插件端口（mcp-plugin.py:202）：

PORT = 13338  # 改为其他端口

启动 MCP 服务器时指定：

python -m ida_pro_mcp.server --ida-rpc http://127.0.0.1:13338

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

如何贡献

Fork 本项目
创建新分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
创建 Pull Request

贡献方向

🐛 Bug 修复
✨ 新功能开发
📝 文档完善
🎨 代码优化
🌍 多语言支持
🧪 测试用例
🔧 安装脚本改进

📝 更新日志

v1.0.1 (2025-01-26) - 完全修复版

🐛 关键修复

✅ 修复缺失的 requirements.txt
✅ 完全修复 Python 3.9 兼容性问题
- 修复版本检查 (3.11 → 3.9)
- 添加 from __future__ import annotations
- 使用 typing_extensions.NotRequired 兼容
- 修复 TypedDict 和 Generic 继承问题
✅ 修正依赖版本冲突 (typing-inspection 0.9.0 → 0.4.0)
✅ 防止 IDA Pro 启动失败（采用独立 Python 环境）

✨ 新增功能

✅ 自动安装脚本 (install.sh)
✅ 自动测试脚本 (test_plugin.py)
✅ 完整的测试套件（4 项测试）
✅ 详细的故障排除文档

📝 文档改进

✅ 完善的安装指南（macOS/Windows/Linux）
✅ 工作原理图示
✅ 6+ 个常见问题 FAQ
✅ 测试和验证指南

✅ 测试状态

✅ 插件语法检查通过
✅ Python 3.9 兼容性验证
✅ 所有依赖安装成功
✅ IDA Pro 可以正常加载插件

v1.0.0 (原版)

基于 mrexodia/ida-pro-mcp
增强混淆检测
增强算法识别
结构化报告生成

📝 开源协议

本项目基于 MIT License 开源。

致谢

原始项目：mrexodia/ida-pro-mcp by Duncan Ogilvie
增强版本：namename333/idapromcp_333 by Chenjun Wang
感谢所有贡献者和社区支持

📞 联系方式

Issues: GitHub Issues
Discussions: GitHub Discussions

🌟 Star History

如果本项目对您有帮助，请点亮 ⭐ Star 支持我们！

Name		Name	Last commit message	Last commit date
src/ida_pro_mcp		src/ida_pro_mcp
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
FINAL_SUMMARY.md		FINAL_SUMMARY.md
LICENSE		LICENSE
README.md		README.md
TESTING.md		TESTING.md
ida-plugin.json		ida-plugin.json
install.sh		install.sh
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
test_plugin.py		test_plugin.py

Latest commit

History

Folders and files

Repository files navigation