# Unreal MCP — AI Game Developer Wiki

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

本页由英文机器翻译而成。[阅读英文原文](https://ai-game.dev/docs/wiki/unreal)。

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](https://ai-game.dev) 的托管服务器（**Cloud** 模式）。你也可以在自己的机器上运行共享的本地服务器 `gamedev-mcp-server`（**Custom** 模式）。
- **你的 AI 客户端**。任何 MCP 客户端都能连接到同一个服务器，并通过它访问你的编辑器。

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

- **AI Game Dev** 桌面应用会为你把插件安装到 Unreal 项目中，并可打开编辑器。无需 Node.js。参见[应用 wiki](https://ai-game.dev/zh-hans/docs/wiki/app)。
- **`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 页面

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

## 接下来看什么

- 初次使用？请先阅读[安装](https://ai-game.dev/zh-hans/docs/wiki/unreal/installation)，然后看[快速上手](https://ai-game.dev/zh-hans/docs/wiki/unreal/getting-started)。
- 想要简明版？[Unreal Engine 安装页面](https://ai-game.dev/zh-hans/engines/unreal)和[快速开始](https://ai-game.dev/zh-hans/docs/quickstart)涵盖了要点。
- 想了解工具详情？请浏览 [Unreal 工具目录](https://ai-game.dev/docs/tools/unreal) 和 [Unreal 最佳实践](https://ai-game.dev/docs/best-practices/unreal)。
- 同时使用其他引擎？请参阅 [Unity wiki](https://ai-game.dev/zh-hans/docs/wiki/unity) 和 [Godot wiki](https://ai-game.dev/zh-hans/docs/wiki/godot)。这三个插件共用同一个服务器、账户和 AI 客户端。

- [**安装** 使用 AI Game Dev 应用或 unreal-mcp-cli 为 Unreal Engine 5.5+ 安装 Unreal MCP 插件。包含环境要求、更新、卸载与 Fab 状态。](https://ai-game.dev/zh-hans/docs/wiki/unreal/installation)
- [**入门** 首次连接 Unreal MCP，登录 ai-game.dev，配置好 AI 客户端，并在 Unreal Editor 中运行你的第一批 AI 提示词。](https://ai-game.dev/zh-hans/docs/wiki/unreal/getting-started)
- [**连接 AI 客户端** 通过 ai-game.dev 云端端点或本地服务器，将 Claude Code、Cursor、Copilot、Codex、Gemini 等 MCP 客户端连接到 Unreal MCP。](https://ai-game.dev/zh-hans/docs/wiki/unreal/connecting-ai-clients)
- [**配置** 配置 Unreal MCP：AI Game Developer 窗口、MCP Tools 可见性、项目配置文件、.env 以及所有 UNREAL\_MCP\_\* 环境变量。](https://ai-game.dev/zh-hans/docs/wiki/unreal/configuration)
- [**工具** 27 个内置 Unreal MCP 工具——RQL、蓝图、C++ 源码、Python、截图与控制台，以及 Unreal Editor 中 AI 的示例提示词。](https://ai-game.dev/zh-hans/docs/wiki/unreal/tools)
- [**扩展** Unreal MCP 的可选扩展：Control Rig、Enhanced Input、GAS、Landscape 与 Water、Niagara 和 PCG。各自的作用及安装方法。](https://ai-game.dev/zh-hans/docs/wiki/unreal/extensions)
- [**自定义工具** 通过任意 C++ 插件向 Unreal MCP 添加你自己的 AI 工具、RQL 模块、提示词和资源，并在运行中的游戏里暴露玩法工具。](https://ai-game.dev/zh-hans/docs/wiki/unreal/custom-tools)
- [**CLI 参考** 完整的 unreal-mcp-cli 命令参考 - 安装 Unreal MCP 插件、登录、配置 AI 代理、打开编辑器、运行工具和 Python。](https://ai-game.dev/zh-hans/docs/wiki/unreal/cli)
- [**故障排查** 解决常见的 Unreal MCP 问题：插件无法加载、缺少 bridge、连接卡住、AI agent 没有 Unreal 工具、构建过期以及工具报错。](https://ai-game.dev/zh-hans/docs/wiki/unreal/troubleshooting)
- [**常见问题** 关于 Unreal MCP 的常见问题解答：支持的引擎版本、AI 客户端、纯蓝图项目、Fab、离线使用、费用以及打包游戏。](https://ai-game.dev/zh-hans/docs/wiki/unreal/faq)

---

Source (HTML): https://ai-game.dev/zh-hans/docs/wiki/unreal

Machine-translated (zh-Hans) from the English page: https://ai-game.dev/docs/wiki/unreal