title: “Unreal Mcp — Automate Unreal Engine editor scenes, actors, and renders” sidebar_label: “Unreal Mcp” description: “Automate Unreal Engine editor scenes, actors, and renders”

{/* 本页面由 website/scripts/generate-skill-docs.py 根据技能对应的 SKILL.md 文件自动生成。请直接编辑源文件 SKILL.md，而非此页面。 */}

Unreal Mcp

用于自动化处理 Unreal Engine 编辑器中的场景、角色及渲染任务。

技能元数据

参考：完整的 SKILL.md 文件

:::info 以下是当触发该技能时 Hermes 所加载的完整技能定义。技能激活后，代理程序会将此内容视为操作指令。

::

Unreal Engine MCP 技能

Hermes MCP 目录中 unreal-engine 项的配套技能。该 MCP 服务器（Epic 官方推出的实验性“Unreal MCP”插件，内部编号为 ModelContextProtocol）运行在 Unreal Editor 进程内部，将编辑器功能以类型化工具的形式呈现出来。本技能旨在教授如何高效地使用这些工具：探索实时可用的工具界面、安全地安排操作顺序、将通俗的请求转化为效果出色的场景，以及通过视觉方式验证成果。用户仅需启动编辑器，无需再手动进行其他操作。

适用场景

当用户需要在虚幻引擎中完成各类操作时即可使用该功能：构建或设计场景、生成/移动/删除游戏对象、设置光照与氛围、创建或调整材质实例、规划摄像机拍摄角度、截取屏幕截图或渲染图像、导入资源、查看场景或用户界面、运行自动化测试，或是为编辑器编写脚本。它既适用于单一操作（如“将太阳设置为黄金时刻效果”），也适用于完整的多步骤项目（如“为我创建一个带有营火的氛围感森林空地，并对其进行渲染”）。

不适用于：DCC风格的网格建模/雕刻操作（可在Blender中建模后再导入结果），也不适用于编辑虚幻引擎的C++项目源代码（那是常规的编程工作——应使用终端；该功能专注于实时编辑器操作）。

先决条件

需按以下顺序完成两个步骤：在Hermes连接之前，必须先启动编辑器端。

编辑器端的一次性设置

1. 已打开项目的 Unreal Editor 5.8+ 版本。（macOS 系统需完整安装 Xcode 并接受其许可协议——否则编辑器在首次启动时会直接退出；详情请参阅相关注意事项。）
2. 进入 Edit > Plugins，启用 Unreal MCP（其依赖的 Toolset Registry 会自动被启用）。系统提示时请重启编辑器。
3. 所有的工具集均为独立于服务器提供的文件：请在同一个插件管理界面中同时启用 AllToolsets 插件。Unreal MCP 本身并不包含任何工具——正是 AllToolsets 提供了那些预装的工具集（如 SceneTools、ActorTools、MaterialInstanceTools、ObjectTools 等）；如果省略此插件，虽然服务器能够连接成功，但代理程序将没有可调用的工具。
4. 进入 Edit > Editor Preferences > General > Model Context Protocol，启用 Auto Start Server。默认绑定地址为 http://127.0.0.1:8000/mcp（端口和路径可在同一界面中进行配置；服务器名称为 unreal-mcp）。如需手动启动服务器，可在编辑器控制台中输入 ModelContextProtocol.StartServer 命令（使用反引号键）。

Hermes 端只需执行一次的操作

hermes mcp install unreal-engine

该命令会创建一个名为 mcp_servers.unreal-engine 的 HTTP 配置项，指向 http://127.0.0.1:8000/mcp，并主动向该服务器查询可用的工具。请在编辑器与服务器均处于运行状态时执行此命令，这样才能确保查询到真实的工具列表。如果用户在“编辑器偏好设置”中更改了端口或路径，则需同步修改 ~/.hermes/config.yaml 文件中 mcp_servers.unreal-engine 下的 url 值以保持一致。

请勿在 Hermes 中使用 ModelContextProtocol.GenerateClientConfig——该函数是为 Claude Code/Cursor 等工具生成 .mcp.json 格式的配置文件。Hermes 会通过 config.yaml 中的配置项来建立连接。

每次会话流程

1. 启动 Unreal Editor，等待项目加载完成；确认服务器已启动（可在输出日志中查看绑定地址，或手动运行 ModelContextProtocol.StartServer）。
2. 启动 Hermes 会话。相关工具会以 mcp_unreal_engine_* 的形式注册。如果未出现这些工具，说明编辑器尚未启动——请先启动编辑器，然后再打开新的 Hermes 会话。
3. 进行合理性检查：调用 mcp_unreal_engine_list_toolsets 并确认能获取到工具集列表。

工具展示方式：动态发现而非固定列表

默认情况下，该插件以工具搜索模式运行：tools/list 只会返回三个元工具，所有实际工具都需要通过这些元工具来访问。在 Hermes 中，这些工具的呈现形式如下：

工具的发现过程始终遵循以下顺序：

1. list_toolsets → 查看该项目实际具备哪些功能组
   （具体内容取决于项目配置：已启用的插件、游戏功能插件以及任何自定义工具集都会影响结果）。返回的名称均为完整限定形式（如 editor_toolset.toolsets.scene.SceneTools、EditorToolset.EditorAppToolset），可直接将其作为 toolset_name 使用。
2. 对目标功能组调用 describe_toolset → 查看真实的参数结构。切勿猜测参数名称——参数结构才是官方定义的规范。
3. 使用完整的工具集名称、简写的工具名称（如 find_actors，而非带点号的完整形式），以及符合参数结构的参数，来调用 call_tool。

请将本次会话中获取的信息缓存起来；只有当编辑器端发生变更时（如新插件启用、自定义工具集创建或执行了 RefreshTools 命令），才需要重新列出工具集信息。

另一种“即时模式”（在编辑器偏好设置中关闭“启用工具搜索”选项）会将每个工具作为独立的 mcp_unreal_engine_<tool> 条目进行展示，此时工具发现功能会在执行 hermes mcp install/configure 命令时才发生。默认模式即为工具搜索模式，本技能也以此为前提；此外，该模式还能避免在每次 API 调用中包含参数结构信息，因此建议优先使用此模式。

有关已发布的工具集列表、自定义工具集的创建方法以及完整的插件配置/控制台命令参考，可查看 references/tool-surface.md 文档。

运行循环

所有 Unreal 相关任务都遵循相同的运行循环：

1. **先进行检测。**在操作任何内容之前，先列出可用的工具集，再查询场景/关卡的当前状态。切勿假设关卡是空的或处于默认状态。在不太熟悉的项目中，还需检查项目中已注册的智能体技能（通过 call_tool → AgentSkillToolset.ListSkills 查看）：与当前操作匹配的项目技能指令会覆盖该技能的通用默认设置。

2. 分步执行单功能操作。每次 call_tool 操作应对应一个逻辑步骤。服务器会在游戏线程上按顺序执行这些工具——如果执行的是大型复杂操作，编辑器界面将会被冻结直至操作完成，同时还可能引发客户端超时问题。例外情况是：对于包含5次及以上相同类型操作的循环，可使用一次 ProgrammaticToolset.execute_tool_script 在服务器端将它们批量处理，这样仍不会违反顺序执行规则（详见 references/advanced-workflows.md）。

3. **绝不能同时发起重叠调用。**在一个操作轮次中不要批量发送多个 mcp_unreal_engine_* 类型的调用——Hermes 会并行处理这些批量调用，而对游戏线程的并行操作则会导致死锁或失败。必须严格遵循“一次调用、等待结果、再执行下一次”的原则，这一规则优先于一般关于并行工具调用的建议。

4. **务必查看所有返回结果。**许多工具（如蓝图编译、材质编辑、控件创建等）会在响应内容中报告操作是否成功，即便没有出现协议层面的异常。只要结果并非明确显示成功，就应立即停止并进行分析，而非置之不理。在修改属性后，还需将值读回——因为某些属性修改路径实际上并不会产生任何实际效果（详见相关注意事项）。

5. 进行视觉与结构层面的验证。 在完成每个里程碑后，通过查询你所修改的元素或属性来确认当前状态；在构图至关重要的情况下，务必截取视图截图（有关截图选项，请参阅 references/tool-surface.md）；并对该图片使用 vision_analyze 工具进行分析——毕竟你是艺术总监，应由你自己来评判效果）。

6. 频繁保存。 编辑内容仅在内存中存在，直到被保存到对应的包或层级中；如果编辑器崩溃，自上次保存以来的所有更改都将丢失，而且通过 MCP 进行的编辑也无法可靠地撤销。因此，在进行任何大规模修改之前和之后，以及每个里程碑完成后，都应及时保存。

7. 提供具体的报告信息。 需注明相关元素的标签、资源路径（如 /Game/...）、以及截图或渲染文件的存储位置。

工作时的基本准则：

• 单位为厘米；坐标轴规则为Z轴向上、X轴向前；旋转角度以度为单位（旋转器功能：绕X轴滚转、绕Y轴俯仰、绕Z轴偏航）。人类眼睛高度约为165厘米，一扇门的大小约为210×90厘米。完整参数表请参见references/scene-craft.md。
• 内容路径使用完整的包名：项目内容路径为 /Game/Folder/Asset.Asset，引擎基础图形路径则为 /Engine/BasicShapes/Cube.Cube。
• 演员标签（在Outliner中显示，可设置且不唯一）与演员名称（内部存储且唯一）并非同一概念。建议优先通过标签或类查询来定位演员，再保留工具返回的标识符。
• 建议使用符合物理规律的照明参数（勒克斯/坎德拉/开尔文），而非随意设定的亮度数值——但首先需查看现有太阳的光强度，以了解场景的校准规则。模板世界通常将光强度设置为10，而物理值会使其数值大幅上升（具体数值见references/scene-craft.md，校准规则见references/pitfalls.md #12b）。

从自然语言到场景模型

用户提供的是需求而非详细规格。在构建之前先进行转换：

1. 明确需求要点。需确定主题、氛围、时间时段、场景是室内还是室外、风格以及最终输出形式（截图？渲染图？可运行的关卡？）。最多只需询问一轮以澄清疑问，随后便应立即着手执行——你才是技术负责人，切勿用《虚幻引擎》的专业术语来回困扰用户。

2. 规划构建顺序。采用以下高效顺序：先构建关卡/环境框架 → 接着放置主要几何体/网格 → 再设置光照与氛围 → 随后处理材质 → 添加场景装饰细节 → 安排摄像机位置 → 最后进行捕获或渲染。对于多步骤的构建任务，可将该计划以待办清单的形式列出。

3. 按照上述流程逐步构建，每完成一个阶段就截取一张截图。

4. 自我进行艺术指导。将每张截图与需求要点逐一对比：轮廓是否清晰可辨？光线方向和强度是否合理？地平线是否不在正中央？与人类身高参照物相比，比例是否准确？在进入下一阶段之前必须先修正这些问题。

5. 交付成果。以文件形式提供截图或渲染图（路径为MEDIA:），同时附上一份简短总结，说明关卡中包含的内容及其保存位置。

references/recipes.md 文件中收录了完整的构建案例（包括室外日光场景、氛围浓厚的室内场景、黄金时刻风格的影视级画面及渲染结果，以及资产导入与放置流程），其中详细列出了相应的调用顺序与参数值。

参考文件

根据需要加载这些文件；在整个过程中请始终牢记SKILL.md中规定的规则。

常见问题（重点提示，完整列表见 references/pitfalls.md）

• 启动顺序很重要。 首先需启动编辑器与服务器，之后再启动Hermes会话。若缺少mcp_unreal_engine_*工具，说明启动顺序有误。
• 每次只能调用一次。 由于游戏线程为串行处理模式，因此不支持批量调用，也无法同时执行多个操作。
• 每次调用时编辑器界面会冻结。 这是设计使然（属于游戏线程执行逻辑）。在长时间运行的操作中应向用户发出提示，并尽量缩短单次调用的操作量。
• 模态对话框会阻塞所有操作。 若有工具调用打开了模态编辑器对话框（或与其冲突），该调用将会暂停，直到用户手动关闭对话框为止。如果调用长时间挂起，应提示用户在编辑器中检查是否存在对话框。
• 长时间操作的超时问题。 Hermes 的默认单次调用超时时间为 120 秒；而资产导入、大规模场景保存及渲染操作所需时间可能超过此限制。对于那些涉及大量渲染或导入操作的场景，可在 ~/.hermes/config.yaml 文件中调高 mcp_servers.unreal-engine.timeout 的值。
• 过时的工具架构信息。 在编写/热加载工具集或启用插件之后，需在编辑器控制台中执行 ModelContextProtocol.RefreshTools 命令，然后再执行 list_toolsets 命令。若新增了 C++ 层的 UFUNCTION，则必须重启整个编辑器——因为“实时编码”功能无法识别这些新函数。
• 实验性插件特性。 不同引擎版本之间的 API 及工具结构可能会发生变化；因此应以 describe_toolset 提供的信息为准，而非仅依赖内存中的数据，包括本技能所提供的示例在内。当文档描述与实时生成的架构信息不一致时，以实时架构信息为准。
• 服务器访问范围不应超出本地主机。 该服务器按设计仅支持本地回环访问，且不支持身份验证。绝不可建议将其开放为更广的访问范围。
• 许可说明。 服务器在启动时会记录相关信息：通过插件传输至已连接的 LLM 服务的数据属于 UE 使用许可协议（UE EULA，第 6 条(e)款）所规定的受许可技术——用户有责任确保其使用的 LLM 服务提供商不会利用这些数据进行训练。如果用户询问数据处理相关问题，应向其说明这一点。

验证清单

• 在会话开始时（连接正常），list_toolsets 会返回相应的工具集列表。
• 在进行首次编辑之前会先查询场景状态，绝不会假设其为空。
• 每完成一个阶段后，都会重新获取已更改的演员/属性信息，并根据需求文档检查截图内容。
• 每个阶段结束后以及最终阶段，都会保存关卡数据及脏数据包。
• 所有交付成果都会保存在磁盘上（截图和渲染文件的路径均已确认），并且会通过完整路径告知用户具体位置。
• 编辑器始终处于干净状态：没有未处理的弹窗，也没有未保存的意外更改，同时会明确告知用户究竟创建了什么、修改了什么以及修改位置在哪。