常见问题

这里简要回答大家关于 Unreal MCP（Unreal Engine 的 AI Game Developer 插件）问得最多的问题。安装步骤请见 Installation 和 Getting started。

通用#

Unreal MCP 是什么？#

这是一个用于 Unreal Editor 的 C++ 插件，它把编辑器操作暴露为 MCP 工具，因此 Claude Code、Cursor、Copilot、Codex 或 Gemini 等 AI 代理可以检查并修改你的项目。它属于 AI Game Developer，与 Unity 和 Godot 插件并列。

它稳定吗？#

它目前处于 beta 阶段。插件、其桥接程序、unreal-mcp-cli 以及编辑器窗口均已发布并在 CI 中测试，当前版本为 0.26.2。

哪些 AI 客户端可用？#

任何 MCP 客户端均可。unreal-mcp-cli setup-mcp 和编辑器的 AI agent 区域会为 Claude Code、Claude Desktop、Cursor、VS Code 和 Visual Studio Copilot、Rider (Junie)、GitHub Copilot CLI、Gemini、Antigravity、Cline、Open Code、Codex 和 Kilo Code 写入配置，另外还提供一个通用的 custom 配置。参见 Connecting AI clients。

它能配合 Claude Code 使用吗？#

可以。运行 unreal-mcp-cli setup-mcp claude-code --path ./YourProject，在项目文件夹中启动 Claude Code，然后向它询问你的关卡情况。详情见 Connecting AI clients。

环境要求#

支持哪些 Unreal Engine 版本？#

Unreal Engine 5.5 及更新版本。各版本已在 5.5、5.6、5.7 和 5.8 上验证。可选扩展需要 5.7 或更新版本。

支持哪些操作系统？#

Windows (x64)、macOS（Apple 芯片和 Intel）以及 Linux (x64)。

我可以在纯蓝图项目中使用它吗？#

插件会针对你的项目进行编译，因此项目需要支持 C++。先向项目中添加任意一个 C++ 类（这会把项目转为 C++ 项目），然后安装插件。你仍然可以继续用蓝图开发游戏，AI 代理也可以为你编写蓝图。

我需要 Node.js 或 .NET 吗？#

使用 AI Game Dev 应用时不需要。unreal-mcp-cli 需要 Node.js。只有从源码构建桥接程序时才需要 .NET 9 SDK；打包安装版本已内置它。

安装#

它上架 Fab 或 Epic 商城了吗？#

还没有。Fab 上架已在计划中。目前请通过 AI Game Dev 应用 或 unreal-mcp-cli 安装。

如何更新？#

在应用中，当出现 Update Package 按钮时点击它；或运行 unreal-mcp-cli update ./YourProject，该命令还会清理旧的构建缓存。参见 Installation。

插件会进入我发布的游戏吗？#

编辑器工具绝不会：它们仅在编辑器中可用。若要把整个插件（包括其桥接程序）排除在打包构建之外，请在你的 .uproject 中为该插件条目添加 TargetDenyList，具体做法见 Installation。

使用方式#

AI 在 Unreal Editor 中实际能做些什么？#

通过 RQL 查询和修改 Actor、组件、资产、关卡、DataTable、gameplay tag、Project Settings、蓝图图表、控件和 Level Sequence；创建并编译蓝图；读取、写入并编译 C++；运行编辑器 Python；执行控制台命令；以及截取屏幕截图。参见 Tools。

我能撤销 AI 代理所做的操作吗？#

通过 rql-mutate 所做的修改每一步都是一个可撤销操作，因此在编辑器中按 Ctrl+Z 即可还原。对 Project Settings 的写入、gameplay tag 编辑和文件改动（C++ 源码、已保存的资产）不进入撤销历史。这些请使用版本控制。

有 Python 逃生通道吗？#

有。python-execute 可运行拥有完整 unreal API 的 Python，而 unreal-mcp-cli exec 可从终端运行 Python。

我可以添加自己的工具吗？#

可以，在任何 C++ 插件中都能添加，无需 fork Unreal MCP。参见 Custom tools。

AI 能控制我正在运行的游戏吗？#

可以，但需要你主动选择启用。运行时连接在 Play In Editor、Standalone 和打包的 Development 构建中可用，默认关闭，除非你自行编译进去，否则会拒绝 Shipping 构建，并且只暴露你的游戏所注册的工具。参见 in-game tools。

账户、隐私与费用#

我需要 ai-game.dev 账户吗？#

使用 Cloud 模式需要：每台机器通过设备码流程登录一次。在 Custom 模式下，你可以让一切都在本地 gamedev-mcp-server 上运行。参见 authentication。

我可以完全离线或本地工作吗？#

使用自定义模式并搭配本地服务器。请注意，你的 AI 客户端本身可能仍需要自己的互联网连接才能访问其模型提供商。

我的令牌存储在哪里？#

机器登录信息位于 ~/.ai-game-dev/credentials.json；项目级设置位于 Saved/Config/UnrealMcp/，版本控制默认会忽略该目录。切勿提交项目的 .env 文件。参见配置。

该插件收费吗？#

该插件和 unreal-mcp-cli 是基于 Apache-2.0 许可证的开源项目。你的 AI 客户端自身的订阅与 AI Game Developer 无关。

更多帮助#

• 故障排查针对具体错误。
• 通用常见问题和快速开始。
• Unreal Engine 页面提供单页概览。