UEAgent

UEAgent

为 Unreal Engine 5 打造、内置于编辑器的 MCP 服务。
超过 1,500 个工具，让 Claude Code、Cursor 或任何 MCP 客户端都能在 Unreal 中构建，
每项更改都会在运行前经过检查，并在运行后重新读取。

English · 西班牙语

---

UEAgent 是一款适用于 Unreal Engine 5.7 和 5.8 的编辑器插件，让 AI Agent 能通过 Model Context Protocol 操作编辑器。该插件本身就是服务：它直接在编辑器内部提供 Streamable HTTP，中间无需 Python 或 Node 进程。

为什么选择 UEAgent

• 覆盖整个引擎，而非演示功能。 Blueprints 及其图表、材质、动画（AnimBP、 montages、IK、Pose Search）、Niagara、landscapes 和 foliage、World Partition、PCG、Sequencer、 UMG/CommonUI/MVVM、GAS、AI（Behavior Trees、StateTree、EQS、Smart Objects）、音频和 MetaSounds、 USD 和 Interchange、PIE 控制与检查：请参阅工具参考。
• 经过验证，而非想当然。 编辑器调用返回 success: true 并不能证明任何事情，因此每次调用都会经过以下契约检查：
  • 前置条件会拒绝已知会导致编辑器崩溃或卡死的调用，并说明可采取的替代操作；
  • 回读会在调用后重新读取状态，并将未能生效的写入、无法证明任何事情的零值，或错误应用到 PIE 世界的更改报告为失败。
• 保障内容安全。 每次工具调用都是一个撤销步骤，并以工具名称命名，因此按 Ctrl+Z 即可撤销。列为只读内容根目录的第三方库不能通过任何工具保存、重命名、移动或删除；在 Play-in-Editor 运行期间不可靠的调用也会被拒绝。
• 为真实会话而构建。 多个 Agent 可以共享一个编辑器：协议任务在网络线程上运行，每次工具调用则通过单一队列在游戏线程上执行。活动面板（状态栏 > MCP > 活动）会列出每次调用及其耗时和结果。

flowchart LR
    A["AI agent<br/>Claude Code, Cursor, ..."] -- "MCP over HTTP" --> P
    subgraph E["Unreal Editor + UEAgent"]
        P["Preconditions<br/>refuse known crashes"] --> H["Tool<br/>1,500+ of them"] --> R["Readback<br/>re-read the state"]
    end
    R -- "verified result" --> A

了解编辑器内部的服务与外部服务有何不同，以及选择 Unreal MCP 服务时应考虑哪些问题：选择 MCP 服务。

快速开始

让你的 Agent 来操作。 在项目文件夹中打开 Claude Code、Cursor、Codex 或其他 Agent，然后 粘贴：

Install the UEAgent plugin in this Unreal Engine project and connect yourself to it, following https://raw.githubusercontent.com/CarlxsMG/UEAgent/main/llms-install.md

它会执行以下步骤、检查下载文件的 SHA-256，并在进行任何更改前征求你的同意；最后你需要重新加载 MCP 服务。参见 llms-install.md。也可以手动操作：

1. 安装。 从 Releases 下载最新的 UEAgent-*-UE5.8-Win64.zip（或适用于你的引擎的 -UE5.7-），并将其解压到 <YourProject>/Plugins/，或者从源代码构建。

2. 打开项目。 服务启动后，状态栏会显示带绿色圆点的 MCP · 55561 （如果没有显示，请参阅故障排除）。

3. 连接 Agent。 在状态栏菜单中，选择 Connect Claude Code to this project，即可将 unreal 条目写入项目的 .mcp.json；选择 Connect another client，则会为 Cursor、VS Code、Antigravity CLI 和 OpenCode 执行相同操作（并复制 Codex 的命令）。或者，仅为你自己连接：

   claude mcp add --transport http unreal http://127.0.0.1:55561/mcp
   

   任何支持 Streamable HTTP 的 MCP 客户端都可以连接到同一 URL：参见客户端。

4. 提出请求。 例如："创建一个名为 BP_Door 的 Blueprint Actor，包含一个门网格体和一个盒体触发器，并在玩家与触发器重叠时通过时间轴打开门。"

可以提出哪些请求

请求	使用的工具
"创建 BP_Door：包含一个网格体和一个盒体触发器，重叠时通过时间轴打开门。"	create_blueprint、add_component_to_blueprint、build_blueprint_graph、compile_blueprint
"查找 /Game 下所有无法编译的 Blueprint，并告诉我原因。"	find_erroring_blueprints、get_graph_nodes、lint_blueprint_graph
"为 M_Base 创建一个红色变体，并将其应用到此关卡中的箱子上。"	create_material_instance、get_actors_by_class、set_actor_material
"运行关卡，读取玩家的生命值，截取屏幕截图，然后停止。"	start_play_in_editor、get_properties、capture_pie_screenshot、stop_play_in_editor
"剪辑一个镜头：在第 0 帧进行镜头切换、淡入并播放开场音效。"	create_level_sequence、add_camera_cut_track、add_fade_track_to_sequence、add_audio_section
"我的哪些资产仍引用供应商资源包？哪些类继承自它？"	audit_asset_references、audit_class_purity、run_map_check

更多内容请参见示例。

客户端

客户端	说明
Claude Code	可从编辑器状态栏一键连接。它会按需加载工具，因此在 URL 末尾添加 ?tools=all 可让它获取所有工具。
Cursor、VS Code、Windsurf、Claude Desktop、Gemini CLI、Codex	任何支持 Streamable HTTP 的客户端均可使用：参见各客户端的设置说明。

默认情况下，服务会列出核心工具，以及 4 个用于搜索、描述和运行其他工具，或将整个领域添加到列表中的工具。在 URL 末尾添加 ?tools=all 可列出所有工具，添加 ?tools=compact 则只列出 3 个：参见工具列表。

收录目录

UEAgent 收录于：

• 官方 MCP Registry，条目为 io.github.CarlxsMG/UEAgent， 其他目录和客户端会从中读取信息；
• Glama，MCP 服务目录；
• awesome-mcp-servers，Gaming 分类；
• awesome-unreal，Editor 分类。

技能

UEAgent 以开放的 Agent Skills 格式提供 Agent 技能，适用于 Claude Code、Codex、Cursor、VS Code、 Antigravity CLI、Gemini CLI 和 OpenCode。从编辑器状态栏将它们安装到项目中： MCP · 55561 > Skills。这些技能随插件一起提供，因此始终与插件的工具保持一致。

技能
ueagent-skill-builder	将你想重复执行的工作流转化为新技能：查找工具、在编辑器中演练任务、检查结果并编写 SKILL.md
ueagent-blueprint-actor	根据描述创建 Blueprint Actor：组件、图表、干净的编译结果，以及关卡中的实例
ueagent-project-audit	检查哪些内容已损坏、哪些内容可以移除，并按严重程度排序
ueagent-level-lighting	设置户外照明（太阳、天空、天空光、雾），并生成截图
ueagent-report-issue	将错误报告或工具请求整理成 GitHub issue，并附上版本、调用信息和日志
ueagent-contribute-fix	将对插件代码的修改整理成拉取请求，并遵循仓库规则

客户端会在请求匹配时自动加载这些技能。更多信息请参阅 技能。

文档

也可在线查看，提供搜索和工具浏览器：carlxsmg.github.io/UEAgent。

客户端	连接 Claude Code、Cursor、VS Code、Windsurf、Claude Desktop、Gemini CLI 和 Codex
示例	效果良好的提示词及其使用的工具
技能	Claude Code 插件：技能构建器和用它创建的三个技能
工具参考	按领域列出的所有工具
响应与拒绝	调用会返回什么，以及如何解读拒绝或回读判定
常见问题	版本、安全性、成本
故障排除	客户端无法连接或调用被拒绝时的处理方法
架构	调用如何在编辑器中传递，以及相关约定
术语表	文档和工具回答中使用的词语

要求

• Windows（Win64）上的 Unreal Engine 5.7 或 5.8，这是插件声明支持的唯一平台。每个发行版都提供对应引擎版本的 zip；少数工具需要 5.8（参见常见问题）。
• 从源代码构建：需要安装 C++ 工具链的 Visual Studio 2022。
• 插件会启用其工具所用的引擎插件（参见 UEAgent.uplugin），其中包括 PythonScriptPlugin、EditorScriptingUtilities、Niagara、PCG、StateTree、ControlRig、IKRig、 PoseSearch、Interchange 和 USD。Game Features 是个例外：插件不会启用它；项目启用后，其五个工具即可工作。

从源代码构建

将此仓库复制或克隆到 <YourProject>/Plugins/UEAgent，然后打开项目并让 Unreal 构建插件，或者从 IDE 构建编辑器目标。编辑器启动时，日志会显示 MCP HTTP server started on http://127.0.0.1:55561/mcp (... tools ...)。

更新

MCP · 55561 > Check for updates 会向 GitHub 查询最新发行版。如果有更新版本，Download and install 会下载适用于你的引擎版本的 zip，根据发行版的 SHA256SUMS.txt 校验文件，并在编辑器关闭时安装；也可以选择 Restart now 立即安装，该选项会关闭编辑器、安装更新并重新打开编辑器。先前版本会保留在 Saved/UEAgentUpdate/Backup 中；如果新版本无法移入，系统会恢复先前版本。

通过 git clone 安装的版本使用 git pull 更新；从 Fab 安装的副本则通过 Epic Games Launcher 更新。 更新后，请重新连接客户端，以便再次列出工具。

设置

Editor Preferences > Plugins > UEAgent（针对每位用户）：

设置	默认值
启用 HTTP 服务器	开	MCP 服务
HTTP 端口	55561	命令行中的 -McpHttpPort=N 会覆盖此设置
身份验证令牌	空	设置后，每个请求都需要 Authorization: Bearer <token>
显示连接提示	开	启动时，如果项目尚未连接，则提供连接 Claude Code 的选项
启动时检查更新	关	每天最多向 GitHub 查询一次是否有更新版本（参见如何更新？）

Project Settings > Plugins > UEAgent（共享，保存到 Config/DefaultEditor.ini）：

设置	默认值
只读内容根目录	空	第三方库根目录（例如 /Game/SomeMarketplacePack）：工具会拒绝在其中保存、重命名、移动或删除任何内容，血统审计也会将其中的类视为库类
项目内容根目录	/Game	audit_class_purity 的默认范围
派生来源标签	mcp.forkOrigin	fork_class_chain 写入、audit_class_purity 检查的元数据标签

控制台命令

命令
mcp.http.status / mcp.http.restart	服务器状态；重启（也会重新加载工具目录）
mcp.claude.status [path] / mcp.claude.connect [path]	检查/写入 .mcp.json 条目
mcp.clients.status / mcp.clients.connect cursor|vscode|antigravity|opencode [path]	对其他客户端的配置文件执行相同操作
mcp.skills.status / mcp.skills.install / mcp.skills.remove [claude|agents|all]	项目中的 UEAgent 技能（参见 Skills）
mcp.contract.selftest <vectors.json> [quit]	运行契约测试向量（参见 Resources/ContractTests）
mcp.ReadOnlyRootEnforcement 0|1	0 = 仅报告只读根目录下的保存操作，而不拒绝这些操作
mcp.UndoStepPerCall 0|1	0 = 由每个工具自行管理撤销缓冲区，而不是每次调用仅创建一个撤销步骤
mcp.activity [N]	将最近 N 次工具调用（默认 20 次）打印到日志中，与活动面板中列出的内容相同
mcp.update.check / mcp.update.status / mcp.update.download / mcp.update.cancel	检查是否有更新版本；查看更新状态；下载更新（编辑器关闭时安装）；删除已下载的更新

安全

• 服务器仅监听 127.0.0.1。它还会拒绝 Host 不是环回地址（防止 DNS 重绑定）或 Origin 是网页的请求。
• 如果未设置身份验证令牌，此计算机上的任何进程都可以调用它。共享计算机上请设置令牌；.mcp.json 条目会从 ${UEAGENT_TOKEN} 读取令牌。
• 工具以编辑器的权限运行：它们可以运行 Python、读写文件、保存、重命名和删除资产、编辑 .ini 文件以及启动进程（例如打包构建、专用服务器）。 连接 Agent 就等于将编辑器交给它。只读内容根目录可防止工具在你列出的根目录下保存、重命名、移动或删除任何内容。

如需报告漏洞，请参见 SECURITY.md。

隐私

UEAgent 不会发送任何关于你或项目的信息：没有遥测，也没有分析数据。它自身唯一的网络连接是访问 GitHub 检查是否有更新版本：当你点击检查更新时，或在你开启启动时检查更新后（默认关闭）每天启动一次。该请求只会说明发起查询的 UEAgent 版本，不会发送其他信息。服务器仅监听 127.0.0.1，工具的回答会发送到你在同一台计算机上连接的 MCP 客户端。该客户端之后向其模型提供商发送什么内容，由客户端决定。

无障碍

有关编辑器界面和文档在无障碍方面提供了什么、缺少什么，以及如何报告障碍，请参见 ACCESSIBILITY.md。

贡献

如有问题或想法，请前往 Discussions。欢迎提交 Bug 报告和拉取请求：CONTRIBUTING.md 说明了代码的组织方式、如何添加工具，以及合并更改前会进行哪些检查。

许可证

UEAgent 基于 MIT License 发布。

商标

Unreal 和 Unreal Engine 是 Epic Games, Inc. 在美国及其他地区的商标或注册商标。UEAgent 是独立项目，与 Epic Games 无关，也未获其认可。