Claude Code Unreal MCP 教程：连接 UE 5.8 与小场景验收

1. 用独立练习关卡，限定这次只摆五个方块

使用 UE 5.8 的独立练习项目。先手动保存或复制基础关卡到 /Game/Tutorials/L_QR_MCP_Blockout；如果这个路径已存在，改成自己的新路径并同步任务书。保留原关卡，操作只发生在练习副本。

成品目标只是五个基础方块组成的展示台：地面、台座、背景板和左右标记。不生成完整游戏、不下载外部资产，也不修改工程设置、蓝图或其他 Actor。灯光可沿用基础关卡；画面好不好看不替代位置与尺寸验收。

• 先记下编辑器版本、项目根目录和练习关卡路径。
• 五个任务标签统一以 QR_Tut_ 开头，动手前检查同名对象是否已存在。
• 本页展示的是任务与连接方法，读者的实际编辑器结果需自行记录。

• 完整任务范围与关卡回滚约定
• Epic 官方：Unreal MCP（UE 5.8）

2. 启用 Unreal MCP 与 All Toolsets，然后重启编辑器

打开 Edit > Plugins，分别查找并启用 Unreal MCP 和 All Toolsets，按提示重启。官方说明 Toolset Registry 依赖会随之启用。这里使用 Epic 随引擎提供的实验性插件，不套用同名社区服务器的安装步骤。

重启后回到练习关卡，检查插件确实已启用。若当前版本找不到插件，先核对编辑器版本与官方页面；不要用另一个插件的命令或端点代替本页配置。

• 官方 Setup：启用插件

3. 在 Editor Preferences 启动本机 MCP 服务

进入 Edit > Editor Preferences > General > Model Context Protocol。可启用 Auto Start Server；默认端点为 http://127.0.0.1:8000/mcp。若端口冲突，先调整实际端口，再生成客户端配置。

也可以保持自动启动关闭，在编辑器 Console 输入下面的启动命令。查看 Output Log 的实际绑定地址与错误；浏览器打开一个地址并不能代替完整 MCP 会话握手。服务只用于本机，保留回环绑定；官方列出的无认证限制意味着不能将端口暴露到公网。

• 本机 MCP 端点与 apizt 模型 API 地址是两件事，分别核对。
• 编辑器工具在游戏线程串行执行；一次调用完成后才进入下一次。
• 启动失败先看端口占用、插件依赖和 Output Log，不反复发送场景创建请求。

ModelContextProtocol.StartServer

• 官方：服务设置、串行调用与本机限制

4. 由编辑器生成 Claude Code 配置，核对项目根目录

在编辑器 Console 运行 ModelContextProtocol.GenerateClientConfig ClaudeCode。随后查看日志中的写入位置，确认 .mcp.json 位于该项目根目录。配置应指向当前正在运行的本机端点。

下方 JSON 是默认端点的对照样例，不是你的运行收据。以编辑器生成的文件为准；已有 MCP 配置时先保存备份并对比变化，保留其他服务器条目。端口改动后重新生成或核对对应 URL。

• 编辑器 Console 命令：ModelContextProtocol.GenerateClientConfig ClaudeCode。
• 确认项目根目录包含 .uproject，并核对配置生成日志，避免在引擎安装目录启动 Claude Code。
• 下载的 mcp-config-example.json 仅用来逐字段对照，不会覆盖你的实际配置。

{
  "mcpServers": {
    "unreal-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

• 官方：GenerateClientConfig 与 Claude Code 配置格式

5. 从配置所在项目启动 Claude Code，先做只读检查

先启动并确认编辑器服务，再在 .mcp.json 所在的项目根目录启动 Claude Code。下面展示 macOS / Linux 的目录命令；将路径换成自己真实的工程目录。Windows 在终端切换到对应工程根目录后同样运行 claude。

第一条任务只询问当前选中的 Actor 和可用工具，不创建任何对象。默认 Tool Search 会先暴露 list_toolsets、describe_toolset、call_tool 等发现入口；具体场景操作函数和参数以当前返回的 schema 为准。遇到不可用的创建、重命名、设置尺寸或读回能力，就记录缺项并改用手动编辑器操作，避免猜测函数名。

• 只读提示：确认 unreal-mcp 连接，读取当前关卡与选中对象；列出工具集并查看场景操作 schema，暂不修改项目。
• 连接异常时核对编辑器仍在运行、端口和启动目录；需要时重新连接客户端。
• 只有实际收到编辑器信息，才在验收表记录连接通过；不能把配置文件存在当成已连接。

cd "/你的实际路径/UnrealProject"
claude

• 查看分阶段只读检查与场景操作提示
• 官方：从项目根目录连接与 Tool Search

6. 按厘米目标矩阵，串行创建五个 QR_Tut_ 方块

确认处于练习副本后，使用下载提示词逐个创建。下面均为原创目标值，位置为世界坐标中心，尺寸为目标包围盒，旋转均为 0 / 0 / 0 度；不是已完成的实际测量值。UE 默认长度单位是厘米，若项目显示单位已修改，先换算后再填写。

不要把表中厘米尺寸直接填进无单位的 Scale。先确认当前 Cube 的实际基础尺寸及工具参数单位，换算后设置，再读回位置与尺寸；每完成一个方块才创建下一个。已有同名标签时先核对并更新练习对象，避免重复生成。

• 读取当前工具 schema 后再构造参数；本页不硬编码未核对的场景函数。
• 一次只执行一项写操作，并读取真实返回；超时先查询现状，不重发同一个创建任务。
• 初版只设位置、尺寸和标签；材质与灯光作为后续练习，避免把连接排查混进创作效果调试。

• 下载五个 Actor 的目标矩阵
• Epic 官方：默认长度单位为厘米

7. 读回实际值，检查落地、重名和目标关卡

用编辑器或实际可用的只读工具逐项检查：五个任务标签各出现一次、所在关卡正确、中心位置和实际尺寸符合目标。以 ±1 cm 作为本练习的记录容差；这只是原创教学验收规则，不是引擎精度承诺。

地面的上表面应在 Z=0；台座、背景板和左右标记底部也应在 Z=0。查看不同角度检查悬空与穿插，并把实际位置、尺寸、工具返回或本人截图记入空白验收表。任何调用失败都填失败原因，不把目标 CSV 复制为实际结果。

• 下载空白实际值与证据验收表

8. 验收后保存练习副本，不满意就回到备份

通过自己的验收后，保存指定练习关卡；记录关卡路径、实际 Actor 清单和修改内容。若未通过，保留失败记录并回到备份，不让模型删除其他关卡或未知资产。

结束练习后可在编辑器 Console 运行 ModelContextProtocol.StopServer。若启用了 Auto Start Server 并希望下次不自动启动，再在 Editor Preferences 关闭该设置。

选题参考 2026 年 10 月 3 日的抖音 Unreal MCP 样本；本页五方块目标、提示与验收材料为原创。我们核对了官方文档，没有在本次教程制作中执行 UE 场景或付费模型请求。

ModelContextProtocol.StopServer

• 选题线索：2026-10-03 抖音 Unreal MCP 样本
• Epic 官方：服务命令与本机边界

怎样确认已经完成

• 编辑器版本与 Experimental Unreal MCP 实际可用；插件重启后生效。
• 本机服务端点、.mcp.json 与启动目录一致，并实际收到编辑器只读信息。
• 场景工具与参数来自当前 schema；调用串行完成，没有重复创建。
• 五个 QR_Tut_ 标签唯一；实际位置和尺寸记录在验收表，并与目标矩阵对照。
• 只修改练习关卡，保留备份和原关卡；保存或回滚由本人确认。
• 没有把默认配置、目标 CSV 或教学图片当作本次模型执行、游戏成品或实扣结果。

常见问题

资料来源

• Epic 官方：Unreal MCP in Unreal Editor（UE 5.8，2026-10-13 核对）
• Epic 官方：Units of Measurement
• 选题线索：2026-10-03 抖音 Unreal MCP 样本