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

安装

使用 AI Game Dev 应用或 unreal-mcp-cli 为 Unreal Engine 5.5+ 安装 Unreal MCP 插件。包含环境要求、更新、卸载与 Fab 状态。

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

本页介绍如何将 Unreal MCP（面向 Unreal Engine 的 AI Game Developer 插件）安装到项目中。选择一种安装方式，按步骤操作，然后继续阅读快速上手。

环境要求

要求说明
Unreal Engine5.5 或更高版本。正式发布版本已针对 5.5、5.6、5.7 和 5.8 验证。
项目类型一个 C++ Unreal 项目。插件包含需要针对你的项目编译的编辑器模块，因此项目必须能够构建 C++。
C++ 工具链你的 Unreal Engine 版本在你的平台上所需的编译器工具链（例如 Windows 上的 Visual Studio、macOS 上的 Xcode）。
操作系统Windows（x64）、macOS（Apple 芯片和 Intel）以及 Linux（x64）。发布包为以上每种系统都提供了对应的 bridge 构建。
Node.js仅 unreal-mcp-cli 需要：^20.19.0 或 >=22.12.0。桌面应用不需要。
.NET 9 SDK仅当你从源码构建 bridge 时才需要。打包安装已内置。

插件并未在其描述符中固定确切的引擎版本，因此同一个插件可以在更新的引擎版本上加载。

注意： 纯蓝图项目需要先有一个 C++ 模块才能构建插件。在 Unreal Editor 中添加任意 C++ 类（Tools、New C++ Class）即可将其转换为 C++ 项目，或使用 unreal-mcp-cli create-project 创建一个全新的 C++ 项目。

方式 1：AI Game Dev 桌面应用

桌面应用是最简单的方式。它内置了安装逻辑，因此你不需要 Node.js、npm 或终端。

  1. 从下载页面安装 AI Game Dev。应用安装指南会带你完成整个过程。
  2. 使用你的 ai-game.dev 账号登录。
  3. 选择 Open folder… 并选中你的 Unreal 项目文件夹（即包含 .uproject 文件的文件夹）。应用会将其识别为 Unreal 项目。或者使用 Create new project 新建项目，此时插件会自动安装。
  4. 点击侧边栏中的 Install Package。应用会安装最新发布的 Unreal MCP 版本，并先校验下载内容。如果已安装的插件版本更新，应用会保留它。
  5. 点击 Open Editor，以你已登录的会话启动 Unreal Editor，这样插件就会通过 ai-game.dev 连接，无需手动填写 token。

在应用的 CLI 中，相同的操作对应 /install-plugin 和 /open 命令。应用还可以安装可选的扩展。详情见项目与引擎。

方式 2：unreal-mcp-cli

unreal-mcp-cli 发布在 npm 上，可在 Windows、macOS 和 Linux 上使用。它无需克隆仓库，也不需要自身的构建步骤。

全局安装该 CLI：

npm install -g unreal-mcp-cli

或者不安装，直接运行一次任意命令：

npx unreal-mcp-cli@latest status

然后安装插件、登录并打开编辑器：

# 1. Install the UnrealMCP plugin into <project>/Plugins/UnrealMCP
unreal-mcp-cli install-plugin ./YourProject

# 2. Sign in to ai-game.dev once per machine (device-code flow in your browser)
unreal-mcp-cli login

# 3. Open the Unreal Editor for the project
unreal-mcp-cli open ./YourProject

这些命令的作用：

  • install-plugin 会下载与 CLI 版本匹配的插件源码（来自 GitHub release 的 unreal-mcp-plugin-source-<version>.zip），并在解压前校验其签名。被篡改或未签名的下载将被拒绝。适用于你平台的 bridge 已包含在该包内。
  • login 会将你的凭证保存到机器级存储（~/.ai-game-dev/credentials.json），与桌面应用和其他引擎的 CLI 共享。
  • open 会根据项目的 EngineAssociation 找到对应的引擎，在需要编译时先构建原生编辑器模块，并在已知的 Unreal 启动提示（例如 "Missing Modules"）仍然出现时将其关闭。

提示： 安装或更新插件前请先关闭 Unreal Editor。Unreal 无法替换已被运行中的编辑器加载的插件。

方式 3：从源码手动安装

手动安装面向贡献者和插件开发。

  1. 将 Unreal-MCP 仓库 中的 UnrealMCP/ 文件夹复制到 <YourProject>/Plugins/UnrealMCP/。
  2. 源码检出中不含内置 bridge。使用 unreal-mcp-cli bootstrap-local ./YourProject 构建一个（需要 .NET 9 SDK），或将 UNREAL_MCP_BRIDGE_PATH 指向你构建的 bridge。
  3. 打开项目。Unreal 会在首次启动时编译插件的模块。

若要进行实时开发，unreal-mcp-cli install-plugin --junction 会以链接方式引用插件文件夹而不是复制它（Windows）。

Fab / Epic Marketplace

Fab 上架计划中，但尚未上线。在它发布之前，Fab 上没有可安装的内容；请使用应用或 CLI。

检查安装

编辑器启动后，输出日志（Output Log）会打印：

[Unreal-MCP] plugin loaded

你也可以运行 unreal-mcp-cli status --path ./YourProject 查看包、项目、插件和连接状态。

随后插件会以 AI Game Developer 的名称出现在编辑器的 Tools 菜单下。接下来请继续阅读快速入门。

更新插件

  • 应用： 当存在更新的插件版本时，侧边栏会显示 Update Package。
  • CLI： 运行 unreal-mcp-cli update ./YourProject。当版本发生变化时，它会删除已安装插件的 Intermediate/ 文件夹及其编译后的 C++ Binaries/，以便 Unreal 进行干净的重建，同时保留内置的 bridge。添加 --force 可重新安装同一版本，添加 --no-clean 可保留构建缓存。
  • 手动复制： 关闭编辑器，删除 Plugins/UnrealMCP/Intermediate/ 和 C++ 的 Binaries/（保留 Binaries/ThirdParty/），然后重新打开项目。

构建缓存过期是更新看似无效的最常见原因。参见故障排除。

移除插件

unreal-mcp-cli remove-plugin ./YourProject

或者在关闭编辑器的情况下删除 <YourProject>/Plugins/UnrealMCP/。

让插件不进入打包后的游戏

如果你只在编辑器中使用 Unreal MCP 来获得 AI 帮助，可以在你的项目的 .uproject 插件条目中将其排除在打包构建之外：

{
  "Name": "UnrealMCP",
  "Enabled": true,
  "TargetDenyList": ["Game", "Client", "Server"]
}

这样插件在编辑器中仍保持启用，但包括 bridge 在内的任何部分都不会被编译或暂存到打包后的游戏中。不要将任何 UnrealMcp* 模块添加到你的游戏模块的 Build.cs 依赖中：直接依赖会覆盖该拒绝列表。若想在运行中的游戏内使用 AI 工具，请参见游戏内工具。