IDA Pro MCP

IDA Pro MCP 是 IDA Pro 的本地 Model Context Protocol 服务器。它允许 MCP 客户端检查 IDB、向 IDA 请求确定性分析结果，并在明确允许的情况下， 将注释或其他更改写回 IDB。 宿主进程在 IDA 之外运行，默认情况下会为每个会话启动一个独立的 IDA 无头进程。

为什么采用此实现

• 确定性的代理接口： 109 个严格模式的 ida_* 操作，可通过 tools/list 和 ida_help 实时发现。
• 本地优先架构： 宿主与 IDA 运行时通过受令牌保护的环回桥接进行通信； 分析路径中不存在隐藏的 LLM 服务。
• 证据，而不仅仅是聊天： 持久化的发现结果在 IDB 之外保留来源、 置信度、生命周期状态、冲突和审计历史。
• 受保护的变更： 更改 IDB 的操作仍受显式策略 和风险确认控制。
• 广泛的客户端支持： 安装程序可识别 22 种以上的代理 环境及其 JSON、JSON5、TOML 和 YAML 配置形式。

当前版本为 1.0.0a3。这是 alpha 软件。公开的 ida_* 操作名称、模式和 workspace 格式在稳定的 1.0.0 版本发布前可能会发生变化。默认客户端接口包含 109 个精确模式的操作。 使用实时发现获取完整契约：tools/list 会枚举每个 操作及其模式，ida_help(topic="...") 会返回某个操作的确切 参数和示例。

安装之前

你需要：

• IDA Pro 或 IDA Home 9.2 或更高版本，并具有可用的 idat/idat64 可执行文件。 仓库的实时测试证据涵盖 IDA 9.3 和 9.4；9.2 是 声明的兼容性下限。
• 用于宿主和安装程序的 Python 3.11 或更高版本。
• 有权在你计划检查的二进制文件上运行 IDA，以及足够的磁盘 空间用于托管 Python 环境、会话文件和 IDB 副本。
• 支持本地 stdio 服务器的 MCP 客户端，例如 Claude Code、 Codex、OpenCode、Claude Desktop、Cursor、VS Code/Copilot、Windsurf、Cline、 Roo Code、Gemini CLI 或 Antigravity。

常规分析不需要语言模型或嵌入模型。可选的语义搜索功能默认使用本地模型，并且在未配置模型时保持禁用。

默认运行时是 idat：每个会话一个无头 IDA 进程。 idalib 后端是实验性的，需要 IDA 9.3 或更高版本的安装 并激活 idapro 包，首次安装不需要它。

从源代码检出安装

安装程序会在安装根目录下创建一个托管环境，将检出的冻结副本安装到其中，并为支持的客户端位置写入客户端配置。从仓库根目录运行：

python3 install.py

对于已知的 IDA 安装，请显式传入：

python3 install.py --ida-dir /path/to/ida-pro-9.3

对于非交互式运行：

python3 install.py --yes --no-ida-prompt --ida-dir /path/to/ida-pro-9.3

安装程序还可以通过 IDADIR、IDA_DIR、PATH 上的 IDA 可执行文件以及常见安装目录找到 IDA。当存在多个安装时，--ida-version 用于选择版本。使用 --dry-run 先检查计划的更改。

除非你选择或请求，否则安装程序不会下载嵌入模型。它可能会为其内置客户端映射中的每个客户端位置创建或更新配置文件，包括未安装在你机器上的客户端。检查安装根目录中的 install-report.json，并在必要时删除未使用的条目。现有的常规配置文件在更改前会备份；格式错误、符号链接或非普通文件会被拒绝，而不是被覆盖。

安装后重启 MCP 客户端，以便它重新加载配置。

代理框架会实时发现工具接口：tools/list 会枚举每个 操作及其模式，ida_help(topic="...") 会返回确切的参数 和示例。不会安装静态技能文件。

默认安装根目录为：

• Linux 和 macOS：~/.local/share/ida-pro-mcp
• Windows：%LOCALAPPDATA%/ida-pro-mcp

设置 IDA_PRO_MCP_HOME 或传入 --install-root 以选择其他位置。

从发布产物安装

Alpha 版本由 GitHub Actions 构建，并作为预发布版本手动发布。当有发布版本可用时，请从 发布页面下载 bundle.zip 或 bundle.tar.gz 资产及其 SHA256SUMS 文件。验证 校验和，解压捆绑包，并从其顶层 目录运行安装程序：

python3 install.py --yes --no-ida-prompt --ida-dir /path/to/ida-pro-9.3

发布版本还包含用于脚本化 Python 安装的 wheel 和源代码分发。捆绑包是最简单的途径，因为它包含 安装程序以及配置 MCP 客户端所需的所有项目文件。发布版本 为 alpha 质量；在升级前请保留原始二进制文件和 IDB，并阅读发布说明。

连接 MCP 客户端

安装程序会为其已知的客户端配置路径写入 服务器条目。它支持 Gemini CLI、Antigravity、Antigravity IDE、Antigravity CLI、 Claude Code、Codex、Copilot CLI、OpenCode、Claude Desktop、Cursor、VS Code、 Windsurf、Cline 和 Roo Code。 OpenCode 和 Copilot 系列客户端使用不同的配置形式；让 安装程序写入这些文件，或遵循 OpenCode 设置指南。

对于使用通用 JSON 格式的客户端，该条目等同于：

{
  "mcpServers": {
    "ida-pro-mcp": {
      "command": "/path/to/ida-pro-mcp/.venv/bin/python",
      "args": ["-u", "-m", "ida_pro_mcp.host.server"],
      "env": {
        "IDA_PRO_MCP_HOME": "/path/to/ida-pro-mcp",
        "IDADIR": "/path/to/ida-pro-9.3",
        "IDA_MCP_TOOL_SURFACE": "agent"
      }
    }
  }
}

在 Windows 上，使用位于 <install-root>/.venv/Scripts/python.exe 的托管解释器。重要的细节是 托管解释器、-u -m ida_pro_mcp.host.server、所选的 IDA 目录以及 IDA_MCP_TOOL_SURFACE=agent。不要将客户端指向 install.py；该文件是安装程序，而不是 MCP 服务器。

更改客户端配置后，完全重启客户端并检查 ida_help 是否出现在其可用操作中。如果客户端仅显示 旧版宽泛的 tool(action=...) 接口，请检查环境是否选择了 默认的 agent 接口，而不是 IDA_MCP_TOOL_SURFACE=legacy。

第一次有用的会话

首先使用测试二进制文件的绝对路径。打开二进制文件通常会等待 IDA 的初始分析完成；大型二进制文件可能需要时间。

ida_open_binary(binary_path="/absolute/path/to/sample")
ida_session_status()
ida_overview()
ida_list_imports(limit=30)
ida_list_strings(query="http", limit=30)
ida_find(query="main", limit=20)
ida_decompile(address="<address returned by IDA>")
ida_xrefs_to(address="<same address>")

当你需要确切的参数 模式时，使用 ida_help(topic="ida_decompile")。公开操作模式是严格的： 未知参数会被拒绝。 地址可能根据各个操作契约被接受为整数或字符串；在你的客户端中，使用 ida_help 为该操作显示的形式。

对于小型调查记录，workspace 发现操作是：

ida_write_finding(title="Input reaches parser", address="<address returned by IDA>", kind="finding", status="confirmed", confidence=0.8, evidence=[{"type":"call", "value":"recv", "address":"<evidence address>"}])
ida_analysis_brief()
ida_next_target()
ida_export_findings(format="markdown")

Workspace 发现结果与 IDB 编辑分开保存。如果活动策略 允许 workspace 写入，ida_write_finding 会在本地记录发现结果； 否则服务器会返回策略错误。ida_publish_findings(dry_run=true) 会预览 IDB 更改。发布、重命名、修补和其他 IDB 变更 受策略控制，并且在操作公开确认要求时，需要该操作文档中说明的确认。

操作一览

首页保持面向任务，但这个紧凑索引使公开 接口易于浏览。下面每个名称在调用时都带有 ida_ 前缀。 完整的模式和示例可通过 tools/list 和 ida_help(topic="...") 实时获取。

什么是安全的，什么不是

服务器的基线策略是 assist。会话可以收紧操作员的 基线策略，但不能放宽它。策略是确定性的；它不会 因为客户端请求就判定某个高风险操作是安全的。

只读检查是正常的起点。示例包括 ida_overview、ida_find、ida_list_functions、ida_list_strings、 ida_list_imports、ida_decompile、ida_disassemble、ida_xrefs_to、 ida_callers、ida_callees、ida_callgraph、ida_read_bytes 以及 计算操作。这些操作仍会消耗本地文件和 IDA 资源， 并且 MCP 客户端会收到它们的结果。

以下操作会更改持久状态或执行代码，应 视为高影响：

• ida_rename、ida_comment、ida_patch_bytes、函数/类型/段/数据 更改、签名应用、ida_save_idb、快照以及撤销/恢复 操作可能会更改 IDB 或相关状态。
• ida_publish_findings 会将发现结果写入 IDB。先运行其 dry-run 形式； 非 dry-run 形式受门控。
• ida_close_session 会拆除实时 IDA 运行时，从 会话的角度来看是破坏性的。
• ida_python 会在活动 IDA 进程中执行任意 Python。它在安全模式下 被阻止，并且在 正常策略下需要显式风险确认。
• ida_emulate 对于受控检查很有用，但会改变状态的模拟器操作 需要相应的确认。
• ida_til_export 和 ida_til_import 会访问文件系统并受门控。 在适用该保护的情况下，文件系统路径受配置的 memory root 约束。

不要将 --disable-policy 当作便利标志使用。它会设置 IDA_MCP_POLICY_MODE=off 并禁用所有策略门控，包括写入 确认和其他工作流控制。如果调用被拒绝，请阅读该操作的 ida_help 条目，并且仅当该操作的 schema 支持时，才提供确切的确认参数。

当 IDA 仍在执行初始分析时，安全模式会阻止某些 全二进制分析、索引和脚本操作。它旨在保持 早期会话调用范围狭窄；轮询 ida_session_status 或 ida_session_health，而不是绕过该保护。

桥接监听环回地址并使用每会话令牌。它不是 网络服务：不要将桥接端口暴露或转发到不受信任的 网络。将导入的脚本、跟踪、二进制文件、语料库数据和客户端 请求视为不受信任的输入。

隐私和数据处理

正常的宿主到 IDA 路径是本地的。该项目不会在分析路径中运行内置 LLM 服务，并且本地嵌入是选择加入的。这并不会 使整个工作流自动离线：

• 连接的 MCP 客户端会收到路径、符号、字符串、字节、 反编译、发现结果和其他结果。客户端或其模型提供商 可能会根据其自己的账户、模型和保留 设置传输该上下文。IDA Pro MCP 无法控制这些传输。
• 如果你显式选择 Gemini 嵌入后端，服务器会向 Google 发送紧凑的行为签名，而不是完整的反编译。 该签名仍可能包含代码派生的调用、常量、字符串 字面量和控制流信息。对于必须保留在工作站上的二进制文件，请勿启用它。
• 安装程序依赖下载、可选模型和 llama-server 下载、 可选威胁语料库下载以及外部 Rizin/radare2 集成 在启用时可能会发出网络请求。
• 本地缓存、日志、会话元数据、托管 IDB 和 blackboard 可能 包含路径、分析元数据和发现结果。保护安装/数据 目录。如果你将 Gemini AI Studio 密钥传给安装程序，该密钥 可能会被写入生成的 MCP 客户端环境块；优先使用 基于环境的凭据，并检查客户端配置。

对于仅本地设置，请使用默认本地运行时，保持 Gemini 和其他 可选下载禁用，并根据你组织的数据策略配置 MCP 客户端及其模型。“仅本地”仍然需要 检查客户端向其自己的模型提供商发送了什么。

常见故障排除

安装程序找不到 IDA

显式传入安装目录：

python3 install.py --ida-dir /path/to/ida-pro-9.3

你也可以设置 IDADIR 或 IDA_DIR。如果找到多个安装， 使用 --ida-version 9.3 或 --no-ida-prompt 控制选择。确认 所选目录包含可运行的 idat 或 idat64。

客户端不显示 IDA Pro MCP

重启客户端并检查其配置条目。确认其 命令使用托管 venv Python 和 -u -m ida_pro_mcp.host.server，并且 env 块包含正确的 IDADIR。查看 install-report.json；安装程序会记录客户端更新失败，并将 备份保留在已修改文件旁边。OpenCode 和 Copilot 系列配置 形式与通用 JSON 示例不同。

打开二进制文件耗时很长或似乎卡住

正常的 ida_open_binary 调用会等待初始分析。检查 ida_session_status 和 ida_session_health，为大型 二进制文件留出更多时间，并检查安装/数据目录下的每会话日志。 后台打开操作可用，但它适用于 你了解其异步行为和安全模式限制的情况。

写入操作被拒绝

这通常是策略按配置正常工作。使用 ida_help 检查该 操作的确切 schema 及其确认要求。不要添加 任意参数：schema 是严格的。在更改策略之前，查看 IDA_MCP_POLICY_MODE 和 操作员策略文件。禁用所有策略门控是一个 单独的、故意不安全的选择。

语义搜索不可用

语义搜索是可选的，需要索引和兼容的嵌入 后端。普通的列出、搜索、反编译和交叉引用工作 不需要它。要设置可选的本地路径，请使用安装程序的显式 嵌入器选项，例如：

python3 install.py --setup-embedder

安装程序还可以运行 --embedder-doctor、使用显式模型路径，或在 请求时下载选定的模型和 llama-server。模型许可证、 磁盘使用和网络下载由你负责。如果模型 缺失，服务器应报告语义搜索不可用，而不是 假装它已运行。

安装程序拒绝客户端配置

修复报告的 JSON、JSONC 或 TOML 语法并重新运行安装程序。它还会 拒绝符号链接和非普通配置路径，以避免覆盖 意外目标。现有的常规文件会被备份；安装程序的 默认回滚行为可以在后续阶段失败时恢复这些备份。

IDA 会话或运行时失败

检查 ida_session_health、会话日志和桥接日志。确认 客户端使用与安装程序记录的相同安装根目录和 IDADIR。默认 idat 后端为每个会话提供自己的进程；在诊断基本安装时，不要 切换到实验性的 idalib。

参考资料

• 项目 wiki — 面向任务的 安装、调查、编辑和故障排除指南。
• 本地 wiki 页面 — 为内置 wiki 工具提供的相同手写材料。
• 实时操作发现 — tools/list 和 ida_help 公开每个公开操作、schema 和示例。
• 安全模型 — 信任边界、策略模式、 环回传输、会话所有权和文件系统保护。
• 调查 workspace — 发现结果、 证据、目标和导出。
• 智能和嵌入 — 本地和 可选 Gemini 检索后端。
• OpenCode 设置 — OpenCode 配置。
• 架构 — 宿主、IDA 运行时和数据 流，供需要实现细节的读者参考。
• 安全策略 — 报告和安全指南。
• 实时 IDA 测试 — 仓库的测试 对真实 IDA 安装证明了什么、没有证明什么。
• 版本控制和发布清单 以及 变更日志 — alpha 状态和发布历史。
• 文档索引 — 维护的指南、 参考、wiki 页面和研究笔记的完整地图。

有关确切的操作名称，请使用生成的参考，或使用 ida_help 询问正在运行的 服务器。较旧的 tool(action=...) 后端仍可用于兼容性，并通过 IDA_MCP_TOOL_SURFACE=legacy 选择；新的 集成应使用精确 schema 的 ida_* 接口。