主线第 6 步 · 安装与连接

选定一条路线，然后从 1 做到完成

开源版负责“源码 + 外部 MCP”，Fab 版额外提供“Launcher 安装 + 编辑器内 AI”；不要把两条路线的依赖混在一起。

开源版步骤 ↓ Fab 版步骤 ↓
先决定你要从哪里聊天

Codex、Claude、Gemini 等外部 MCP 客户端：两版都使用 Python/uv stdio server。直接在 Unreal Editor 内聊天：仅 Fab 版提供，并且这条路线不需要 Python。

路线 A · 开源版

GitHub 源码 + 外部 MCP 客户端

当前公开源码基线是 UE 5.8 / Win64。需要 Git、可用的 C++ 编译环境、uv，以及一个支持 MCP stdio 的 AI 客户端。

  1. 1

    把仓库克隆到项目 Plugins/UmgMcp

    cd D:\UE5Project\YourProject
mkdir Plugins
cd Plugins
git clone https://github.com/winyunq/UnrealMotionGraphicsMCP.git UmgMcp

    保持最终目录名为 UmgMcp，便于配置和排错。

  2. 2

    用 UE 5.8 打开项目并编译插件

    在 Plugins 中启用 UmgMcp，允许 Unreal Build Tool 构建 Editor 模块，然后重启编辑器。若从旧版本升级，先清理该插件的旧 Binaries/Intermediate。

  3. 3

    安装 uv，并确认 Python server 可以启动

    cd D:\UE5Project\YourProject\Plugins\UmgMcp\Resources\Python
uv run python UmgMcpServer.py

    正常使用时由 MCP 客户端启动 server；这条命令只用于单独排错。

  4. 4

    把 UMG MCP 加到客户端配置

    {
  "mcpServers": {
    "UmgMcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "D:\\UE5Project\\YourProject\\Plugins\\UmgMcp\\Resources\\Python",
        "UmgMcpServer.py"
      ]
    }
  }
}

    目录必须指向 Resources/Python；Windows JSON 路径中的反斜杠需要写成双反斜杠。

  5. 5

    完成第一次只读连接

    list_umg_mcp_servers→ connect_umg_mcp→ set_target_umg_asset→ get_widget_tree

    先确认返回的是正确项目、正确资产和正确控件树，再执行任何写入。

  6. 6

    可选：运行静态协议检查

    uv run python APITest\Umg_Widget_Protocol_Static_Check.py
uv run python APITest\Blueprint_MCP_Schema_Check.py
uv run python APITest\Material_Protocol_Static_Check.py
uv run python APITest\Animation_Protocol_Static_Check.py
路线 B · Fab 版

Fab / Epic Launcher + 编辑器内 AI

v1.0.13 发布包覆盖 UE 5.6、5.7、5.8 / Win64。三个包均使用全新的下载 URL，并通过禁止可执行文件扫描。

  1. 1

    在 Fab 获取插件，并安装匹配的引擎包

    不要把 5.8 包手工复制给 5.6 使用；在 Launcher 中选择与你的 UE 版本一致的插件构建。

    打开 Fab 商品页 →
  2. 2

    启用 UmgMcp 并重启编辑器

    插件包含 UmgMcp、ChatWithUnreal 和 LiteRTLMUnreal 模块；首次启用或切换版本后应完整重启 UE。

  3. 3

    在 Editor Preferences → Plugins → UmgMcp 配置供应商

    Google 登录 / Gemini API 智谱 AI API 自定义 Gemini 或 OpenAI-compatible Endpoint 本地 Codex CLI LiteRT-LM 本地模型

    只配置你准备使用的路线；API 密钥、登录、本地 CLI 和本地模型可以按优先级与失败重试策略组合。

  4. 4

    打开 UMG AI Assistant，并选择 Tool Mode

    UMG、Blueprint、Animation、Material 模式会给内置 Agent 不同的工具白名单；复杂任务也可以由 Task/Agent 层拆分。

  5. 5

    从一个明确、可验证的任务开始

    打开 /Game/UI/WBP_LoginPanel。先读取 Widget Tree 和根容器布局，不要修改；告诉我当前结构和你准备使用的工具。

    确认读取正确后，再发送第二条消息要求增量修改。

  6. 6

    如果仍想从外部 Codex/Claude 控制 Fab 包

    可以。使用上方路线 A 的 Resources/Python MCP 配置；此时仍需要 uv/Python，因为你选择的是外部 MCP 路线。

故障排查

先确认连接层，再看具体工具

现象检查顺序
ConnectionRefusedError / WinError 10061确认 UE 已打开且插件启用；重新 list_umg_mcp_servers；连接存活记录中的动态端口，不要依赖旧固定端口。
连接到了错误项目列出所有实例，根据 project/path 选择，再使用 exclusive=true 连接并设置 target。
工具成功但改错资产先 get_target_umg_asset / get_target_blueprint_asset；写入前传完整资产路径。
Blueprint 或 HLSL 写入后无效执行对应 compile 工具，检查返回诊断，再重新读取图或材质。
Fab 中看不到某个 UE 版本确认商品更新审核状态；v1.0.13 包线包含 5.6/5.7/5.8，并使用与旧提交不同的版本号和下载 URL。

连接成功后，回到标准编辑闭环

Target → Read → Plan → Write → Compile/Save → Read Back。

查看完整工作流 查找具体工具