本页由英文机器翻译而成。阅读英文原文。

Unreal MCP

Unreal MCP 将 Claude、Cursor、Copilot 等 AI 智能体连接到 Unreal 编辑器。了解插件、桥接程序、CLI 与应用如何协同工作。

更新于 2026年11月4日 查看 Markdown 版本

Unreal MCP 是 AI Game Developer 的 Unreal Engine 插件。它让 Claude Code、Cursor、GitHub Copilot、Codex 或 Gemini 等 AI 智能体在 Unreal 编辑器内工作：查询和修改 Actor、组件、资产和关卡，编写并编译蓝图，编辑并编译 C++，运行编辑器 Python，以及截取可供其查看的截图。你用自然语言描述需求，智能体便通过 Model Context Protocol（MCP）调用编辑器的工具。

本 wiki 说明如何安装插件、连接你的 AI 客户端，以及在 Unreal 编辑器中让 AI 产出有用的结果。该插件目前处于 beta 阶段；当前版本为 0.26.2。

各部分如何协同工作

一套 Unreal MCP 环境由四个部分组成。了解它们能让安装和故障排查轻松许多。

  • Unreal MCP 插件（UnrealMCP）。一个安装在项目 Plugins/ 文件夹中的 C++ 编辑器插件。它注册各类 AI 工具，并在编辑器中添加 AI Game Developer 窗口。
  • 桥接程序（unreal-mcp-bridge）。Unreal 编辑器使用 C++，因此 .NET MCP 主机作为编辑器旁的小型辅助进程运行。插件会自动启动它，并通过受令牌保护的本地连接与其通信。发行包已内置桥接程序，因此你无需安装 .NET。
  • MCP 服务器。默认情况下，桥接程序连接位于 ai-game.dev 的托管服务器（Cloud 模式）。你也可以在自己的机器上运行共享的本地服务器 gamedev-mcp-server（Custom 模式）。
  • 你的 AI 客户端。任何 MCP 客户端都能连接到同一个服务器，并通过它访问你的编辑器。

有两款工具可协助你完成这些配置：

  • AI Game Dev 桌面应用会为你把插件安装到 Unreal 项目中，并可打开编辑器。无需 Node.js。参见应用 wiki。
  • unreal-mcp-cli，npm 上的跨平台命令行工具。它可以安装和更新插件、登录账号、写入 MCP 客户端配置、打开编辑器，以及在终端或 CI 中运行工具。

AI 智能体能做什么

该插件提供 7 个类别共 27 个工具。大多数编辑器数据都通过 RQL 处理，即用一套查询语言覆盖整个编辑器，而不是为每种操作提供一个工具：

  • RQL（rql-query、rql-mutate、rql-schema）：查找和修改 Actor、组件、资产、关卡、DataTable、Gameplay Tag、Project Settings、蓝图图表、控件蓝图和关卡序列。
  • 蓝图：创建、编辑和编译蓝图，并给出结构化的错误列表供智能体修复。
  • C++ 源码：读取、生成骨架、编辑和编译项目的 C++（Live Coding 或 Unreal Build Tool）。
  • Python：运行 Python，可使用完整的 unreal 编辑器 API。
  • 截图：视口、游戏视图、摄像机以及孤立 Actor 的截图。
  • Console 和工具列表辅助工具。

六个可选扩展分别增加 Control Rig、Enhanced Input、Gameplay Ability System、Landscape and Water、Niagara 和 PCG 支持。你也可以从任意 Unreal 插件中注册自己的工具。

Wiki 页面

页面你将看到的内容
安装环境要求，以及目前所有可用的安装方式：应用、CLI 和手动安装
快速上手首次连接、最初的提示词，以及验证一切是否正常
连接 AI 客户端Cloud 与 Custom 模式、设备码登录、项目密钥，以及针对各智能体的 setup-mcp
配置AI Game Developer 窗口、MCP Tools 窗口、配置文件以及 UNREAL_MCP_* 变量
工具每一个内置工具，以及该向 AI 提出什么请求
扩展六个可选扩展及其安装方法
自定义工具从 C++ 添加你自己的工具、提示词和资源，包括游戏内（运行时）工具
CLI 参考每一个 unreal-mcp-cli 命令与参数
故障排查连接、桥接程序、构建和工具问题的解决方法
常见问题常见问题的简明解答

接下来看什么