【MCP】ida-pro-mcp 入门实战：安装、启动并用 MCP Inspector 调通四层连通

文章目录

• • 概述
  • 安装前检查
  • 安装与部署
  • • [路线 A：Codex 用户（当前推荐）](#路线 A：Codex 用户（当前推荐）)
    • [路线 B：IDA GUI 插件（兼容路线）](#路线 B：IDA GUI 插件（兼容路线）)
  • [IDA 如何发现 `ida_mcp.py`](#IDA 如何发现 ida_mcp.py)
  • 客户端配置发生了什么
  • 启动与首次调用
  • 限制工具范围
  • 分层排错
  • • [代理启动失败：检查 Python 解释器与环境变量](#代理启动失败：检查 Python 解释器与环境变量)
  • 卸载
  • 总结
  • 参考资料

概述

安装成功的标准不是"命令没有报错"，而是客户端、代理、IDA 插件和 IDB 查询四层全部连通。

本文给出一条可验证的安装路径。素材基线要求 Python 3.11 及以上、IDA Pro 8.3 及以上，推荐 IDA 9.0 及以上；IDA Free 不能加载第三方插件，因此不在支持范围内。

环境项	要求或说明
Python	3.11 及以上
IDA Pro	8.3 及以上，推荐 9.0 及以上
MCP 客户端	至少一个受支持客户端；也可手工配置
Headless	IDA 9.0+ 的 idalib，并先完成激活

安装前检查

先确认三个环境不是"各自可用"，而是能被安装器找到：

1. 在准备运行 ida-pro-mcp 的终端检查 Python。
2. 确认 IDA Pro 可正常启动并加载一个测试二进制。
3. 找到目标 MCP 客户端的配置范围：用户级还是项目级。

IDA 9.0+ 默认附带 Python 3.12。较旧版本若 Python 不满足要求，素材建议使用 IDA 自带的 idapyswitch 工具调整解释器。无头模式还需要运行 IDA 提供的 py-activate-idalib.py，让系统 Python 能导入 idapro。

安装与部署

ida-pro-mcp 不是系统自带命令。直接运行它若提示"无法识别""command not found"，通常表示 Python 包尚未安装，或 Python 的 Scripts 目录没有加入 PATH。

路线 A：Codex 用户（当前推荐）

官方目前推荐 Codex 用户通过插件市场安装；这条路线使用 idalib-mcp，不需要先执行 ida-pro-mcp --install：

codex plugin marketplace add mrexodia/codex-marketplace
codex plugin remove ida-pro-mcp@mrexodia
codex plugin add ida-pro-mcp@mrexodia

如果此前没有安装过该插件，第二条 remove 提示未找到可以忽略。安装后重启 Codex；首次运行可能需要等待 uv 解析依赖。

路线 B：IDA GUI 插件（兼容路线）

官方已说明 GUI MCP 插件不再是推荐方案，未来可能弃用。确实需要 GUI 插件时，先安装当前 GitHub 主分支版本：

python -m pip uninstall -y ida-pro-mcp
python -m pip install "https://github.com/mrexodia/ida-pro-mcp/archive/refs/heads/main.zip"
python -m ida_pro_mcp.server --install

最后一条使用模块方式启动，不依赖 ida-pro-mcp 可执行文件是否在 PATH 中。若下面的命令能输出帮助，则也可以继续使用官方 README 中的短命令：

ida-pro-mcp --help
ida-pro-mcp --install

安装器会同时处理两件事：把插件部署到 IDA 用户插件目录，并向检测到的 MCP 客户端写入服务器配置。若需要手工配置，可使用同样稳妥的模块调用：

python -m ida_pro_mcp.server --config

插件由两部分构成：轻量加载器 ida_mcp.py 和实际包目录 ida_mcp/。

IDA 用户插件目录/
├── ida_mcp.py      # 插件入口与热重载加载器
└── ida_mcp/        # HTTP、RPC、同步层及 API 模块

常见插件目录如下：

平台	用户插件目录
Windows	%APPDATA%\Hex-Rays\IDA Pro\plugins\
macOS / Linux	~/.idapro/plugins/

安装器优先创建符号链接，便于开发时热重载；失败后会退回文件复制。Windows 创建符号链接通常需要开启开发者模式或具备相应权限。

IDA 如何发现 ida_mcp.py

IDA 并不是根据 Python 包名寻找 MCP，而是在启动时扫描插件搜索路径中的脚本。ida_mcp.py 位于 plugins/ 目录后，会按下面的顺序被加载：

IDA 启动
  └─ 扫描用户目录与安装目录下的 plugins/
      └─ 导入 ida_mcp.py
          └─ 调用全局 PLUGIN_ENTRY()
              └─ 得到 idaapi.plugin_t 实例
                  └─ 根据 wanted_name = "MCP" 注册菜单与快捷键

文件名负责让 IDA 发现并导入脚本，真正表明"这是一个 IDA 插件"的是脚本中的 PLUGIN_ENTRY()。它返回继承自 idaapi.plugin_t 的 MCP 实例；类中的 wanted_name = "MCP" 决定 Edit → Plugins → MCP 的菜单名称，wanted_hotkey = "Ctrl-Alt-M" 则声明默认快捷键。初始化完成后，加载器再按需导入旁边的 ida_mcp/ 包，因此入口脚本和实现目录缺一不可。

class MCP(idaapi.plugin_t):
    flags = idaapi.PLUGIN_KEEP
    wanted_name = "MCP"
    wanted_hotkey = "Ctrl-Alt-M"

def PLUGIN_ENTRY():
    return MCP()

IDA 的用户目录可以被环境变量 IDAUSR 覆盖。Windows 未设置该变量时，默认用户插件目录是 %APPDATA%\Hex-Rays\IDA Pro\plugins；设置后，应以 IDA 自己报告的搜索路径为准。可以在 IDA 的 Python Console 中检查：

import ida_diskio

print("用户目录：", ida_diskio.get_user_idadir())
print("插件搜索路径：")
for path in ida_diskio.get_ida_subdirs("plugins"):
    print("  ", path)

如果菜单没有出现，先检查实际搜索路径中是否同时存在 ida_mcp.py 和 ida_mcp/。只有旧版 mcp-plugin.py、只安装了 Codex 的 idalib-mcp，或者安装器写入的目录不在当前搜索路径中，都不会加载新版 GUI 菜单。

客户端配置发生了什么

默认 stdio 模式下，MCP 客户端启动 Python 子进程，由该进程运行代理。安装器会寻找正确的 Python 可执行文件，并转发 PYTHONHOME、PYTHONPATH、PYTHONUSERBASE 等关键变量，减少客户端后台环境与交互终端不一致的问题。

配置更新使用临时文件加原子替换，避免写入途中中断造成配置损坏。
#mermaid-svg-XePw0zfNd04jv1eP{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-XePw0zfNd04jv1eP .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-XePw0zfNd04jv1eP .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-XePw0zfNd04jv1eP .error-icon{fill:#552222;}#mermaid-svg-XePw0zfNd04jv1eP .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-XePw0zfNd04jv1eP .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-XePw0zfNd04jv1eP .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-XePw0zfNd04jv1eP .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-XePw0zfNd04jv1eP .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-XePw0zfNd04jv1eP .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-XePw0zfNd04jv1eP .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-XePw0zfNd04jv1eP .marker{fill:#333333;stroke:#333333;}#mermaid-svg-XePw0zfNd04jv1eP .marker.cross{stroke:#333333;}#mermaid-svg-XePw0zfNd04jv1eP svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-XePw0zfNd04jv1eP p{margin:0;}#mermaid-svg-XePw0zfNd04jv1eP .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-XePw0zfNd04jv1eP .cluster-label text{fill:#333;}#mermaid-svg-XePw0zfNd04jv1eP .cluster-label span{color:#333;}#mermaid-svg-XePw0zfNd04jv1eP .cluster-label span p{background-color:transparent;}#mermaid-svg-XePw0zfNd04jv1eP .label text,#mermaid-svg-XePw0zfNd04jv1eP span{fill:#333;color:#333;}#mermaid-svg-XePw0zfNd04jv1eP .node rect,#mermaid-svg-XePw0zfNd04jv1eP .node circle,#mermaid-svg-XePw0zfNd04jv1eP .node ellipse,#mermaid-svg-XePw0zfNd04jv1eP .node polygon,#mermaid-svg-XePw0zfNd04jv1eP .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-XePw0zfNd04jv1eP .rough-node .label text,#mermaid-svg-XePw0zfNd04jv1eP .node .label text,#mermaid-svg-XePw0zfNd04jv1eP .image-shape .label,#mermaid-svg-XePw0zfNd04jv1eP .icon-shape .label{text-anchor:middle;}#mermaid-svg-XePw0zfNd04jv1eP .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-XePw0zfNd04jv1eP .rough-node .label,#mermaid-svg-XePw0zfNd04jv1eP .node .label,#mermaid-svg-XePw0zfNd04jv1eP .image-shape .label,#mermaid-svg-XePw0zfNd04jv1eP .icon-shape .label{text-align:center;}#mermaid-svg-XePw0zfNd04jv1eP .node.clickable{cursor:pointer;}#mermaid-svg-XePw0zfNd04jv1eP .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-XePw0zfNd04jv1eP .arrowheadPath{fill:#333333;}#mermaid-svg-XePw0zfNd04jv1eP .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-XePw0zfNd04jv1eP .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-XePw0zfNd04jv1eP .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-XePw0zfNd04jv1eP .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-XePw0zfNd04jv1eP .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-XePw0zfNd04jv1eP .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-XePw0zfNd04jv1eP .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-XePw0zfNd04jv1eP .cluster text{fill:#333;}#mermaid-svg-XePw0zfNd04jv1eP .cluster span{color:#333;}#mermaid-svg-XePw0zfNd04jv1eP div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-XePw0zfNd04jv1eP .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-XePw0zfNd04jv1eP rect.text{fill:none;stroke-width:0;}#mermaid-svg-XePw0zfNd04jv1eP .icon-shape,#mermaid-svg-XePw0zfNd04jv1eP .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-XePw0zfNd04jv1eP .icon-shape p,#mermaid-svg-XePw0zfNd04jv1eP .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-XePw0zfNd04jv1eP .icon-shape .label rect,#mermaid-svg-XePw0zfNd04jv1eP .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-XePw0zfNd04jv1eP .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-XePw0zfNd04jv1eP .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-XePw0zfNd04jv1eP :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 安装包后运行模块 --install
检测 IDA 插件目录
检测 MCP 客户端
符号链接或复制插件
生成客户端配置
临时文件写入
原子替换原配置

启动与首次调用

安装结束后按这个顺序操作：

1. 完全退出并重新启动 IDA Pro。
2. 在 IDA 中加载一个二进制。
3. 通过 Edit → Plugins → MCP 或快捷键启动插件。
4. 完全退出并重新启动 MCP 客户端；部分客户端需要从托盘退出后台进程。
5. 让客户端读取 IDB 元数据或列出函数，验证只读调用。

插件默认监听 127.0.0.1:13337。如果端口已占用，它会继续尝试后续最多 100 个端口。主机和起始端口可在 Edit → Plugins → MCP Configuration 中调整。

客户端发起 tools/call
        │
        ▼
ida-pro-mcp 代理
        │ 发现可用实例
        ▼
IDA 插件 HTTP 服务
        │ 主线程执行
        ▼
返回 IDB 查询结果

限制工具范围

profile 是工具白名单文本。项目提供两种典型思路：

profile	用途	典型能力
triage	第一次快速盘点	函数列表、导入、反编译等少量工具
readonly	完整只读分析	分析、读取内存、查询类型，不修改 IDB

刚完成首连时优先使用只读能力。这样即使提示理解有偏差，也不会直接更改数据库。

分层排错

调用失败
├─ 客户端没看到服务器：检查配置文件和客户端重启
├─ 代理启动失败：检查 Python 解释器与环境变量
├─ 提示 IDA 未连接：打开二进制并启动 MCP 插件
├─ 端口冲突：检查插件实际监听端口和配置
└─ 工具不可见：检查 profile、扩展组和 unsafe 设置

代理找不到插件时会返回 JSON-RPC 错误 -32000，并提示启动插件的快捷键。这个错误说明 MCP 客户端已经到达代理，问题范围应缩小到 IDA 实例发现和插件服务。

代理启动失败：检查 Python 解释器与环境变量

ida打开pe文件，发现如下报错：

根据错误信息，可以看到python为3.9，不符合要求，这里更换为3.13：

• 在ida同目录下找到idapyswitch.exe进程，打开该软件
• 选择我们需要的python版本（这里选择1）
• 重新打开ida即可。

[MCP] Autostarting server...
Exception in ida_kernwin.UI_Hooks dispatcher function: SWIG director method error. Error detected when calling 'UI_Hooks.ready_to_run'
Traceback (most recent call last):
  File "C:/Users/Knine/AppData/Roaming/Hex-Rays/IDA Pro/plugins/ida_mcp.py", line 212, in ready_to_run
    self.plugin.run(0)
  File "C:/Users/Knine/AppData/Roaming/Hex-Rays/IDA Pro/plugins/ida_mcp.py", line 288, in run
    from ida_mcp import MCP_SERVER, IdaMcpHttpRequestHandler
  File "C:\Users/Knine/AppData/Roaming/Hex-Rays/IDA Pro/plugins\ida_mcp\__init__.py", line 23, in <module>
    from . import rpc
  File "C:\Users/Knine/AppData/Roaming/Hex-Rays/IDA Pro/plugins\ida_mcp\rpc.py", line 4, in <module>
    from .zeromcp import (
  File "C:\Users/Knine/AppData/Roaming/Hex-Rays/IDA Pro/plugins\ida_mcp\zeromcp\__init__.py", line 3, in <module>
    from .mcp import (
  File "C:\Users/Knine/AppData/Roaming/Hex-Rays/IDA Pro/plugins\ida_mcp\zeromcp\mcp.py", line 410
    match urlparse(self.path).path:
          ^
SyntaxError: invalid syntax
---------------------------------------------------------------------------------------------
Python 3.9.9 (tags/v3.9.9:ccb0e6a, Nov 15 2021, 18:08:50) [MSC v.1929 64 bit (AMD64)] 
IDAPython 64-bit v9.0.0 final (serial 0) (c) The IDAPython Team <idapython@googlegroups.com>
---------------------------------------------------------------------------------------------

卸载

卸载流程会从已检测客户端配置中移除 ida-pro-mcp 条目，并删除 IDA 用户目录中的插件文件。执行前建议先关闭 IDA 和相关 MCP 客户端，以免后台进程继续占用文件或在退出时覆盖配置。

总结

一次可靠的安装需要验证四层：客户端能看到服务器、代理能运行、插件能监听、只读 IDB 调用能返回。安装器负责插件和客户端配置，但重启顺序、二进制加载状态与 profile 仍需人工确认。

最小可照抄流程

# 1. 装包并安装插件+客户端配置
python -m pip install "https://github.com/mrexodia/ida-pro-mcp/archive/refs/heads/main.zip"
python -m ida_pro_mcp.server --install
python -m ida_pro_mcp.server --config

# 2. 启动 IDA，加载二进制，Ctrl-Alt-M 启动 MCP 插件

# 3. Inspector 连 HTTP 端点
npx @modelcontextprotocol/inspector
# 或者执行全局命令： mcp-inspector
# 界面填 http://127.0.0.1:13337/mcp

# 4. CLI 快速列工具
npx @modelcontextprotocol/inspector --cli \
  --server-url http://127.0.0.1:13337/mcp \
  --transport http \
  --method tools/list

# 5. 调只读工具
npx @modelcontextprotocol/inspector --cli \
  --server-url http://127.0.0.1:13337/mcp \
  --transport http \
  --method tools/call \
  --tool-name get_metadata \
  --tool-args-json '{}'

参考资料

• 【MCP】MCP Inspector 入门实战：把你的第一个 MCP Server 调通
• DeepWiki：Installation and Setup
• DeepWiki：Basic Usage Guide
• DeepWiki：MCP Proxy Server
• DeepWiki：IDA Pro Plugin