UnrealMCP — 面向 Unreal Engine 5.7 的原生 MCP

英文 | 简体中文

UnrealMCP 是一个自包含的 Unreal Engine 5.7 编辑器代码插件。它允许 Codex 和其他本地 MCP 客户端检查和控制已打开的 Unreal Editor，同时只暴露一个 MCP 工具：unreal。

随附的插件不需要 Node.js、npm、Python 包或单独安装的网关服务。它包含两个运行时组件：

• Binaries/Win64/UnrealMCPGateway.exe — 由 MCP 客户端启动的原生 C++ stdio MCP 服务器。

• Binaries/Win64/UnrealEditor-UnrealMCP.dll — 拥有回环工作器并将 Unreal 工作分发到 Game Thread 的编辑器模块。

亮点

• 单工具接口： 发现、健康检查、执行和异步任务控制都位于 unreal 之后。

• 自包含： 可分发插件包含原生 stdio 网关和 Unreal Editor 工作器。

• 智能体友好： 有序的 Python/控制台批处理为反射的 UE API 和项目特定系统（如 UnLua）提供了灵活路径。

• Game Thread 安全： UObject 和编辑器操作被分发到 Unreal Game Thread。

• 面向 Fab 的打包： 发布自动化生成干净的单插件 ZIP，无需外部运行时。

flowchart LR
    C["Codex / MCP client"] -->|"stdio JSON-RPC"| G["Native gateway EXE"]
    G -->|"127.0.0.1 HTTP + optional bearer token"| P["UnrealMCP Editor plugin"]
    P -->|"Game Thread"| U["UE Python / console / UObject APIs"]

状态和兼容性

能力目录覆盖了 UE 5.8 官方 AllToolsets 聚合所启用的每个插件组，并借助 UE 5.7 Python/反射和控制台机制实现。仅存在于 UE 5.8 中的子系统无法在标准 UE 5.7 中创建；当所需的 5.7 子系统或可选插件可用时，等效工作流可以工作。请参阅 能力覆盖。

目录

• 快速开始

• 安装

• 连接 Codex

• 验证首次连接

• 单工具 API

• 能力模型

• 从源码构建

• 测试

• 故障排查

• 安全与操作限制

• 仓库结构

• 分发说明

快速开始

1. 解压插件，使描述文件位于 <Project>/Plugins/UnrealMCP/UnrealMCP.uplugin，并且没有额外的嵌套目录。

2. 启用 Minimal MCP for Unreal Editor 和 Python Editor Script Plugin，然后重启 Unreal Editor。

3. 将下面的配置保存到用户级 ~/.codex/config.toml 或受信任项目中的 .codex/config.toml。将命令替换为网关的绝对路径。

4. 重启 Codex，使用 /mcp 确认 unreal 已连接，并让代理调用 health 操作。

[mcp_servers.unreal]
command = "C:/absolute/project/path/Plugins/UnrealMCP/Binaries/Win64/UnrealMCPGateway.exe"
startup_timeout_sec = 15
tool_timeout_sec = 3600

健康的结果包括 ok: true、实际引擎版本、is_game_thread: true 和 python_loaded: true。Unreal Editor 必须保持打开，并加载目标项目。

安装

项目安装

在复制或替换二进制文件之前，请关闭 Unreal Editor。将打包的 UnrealMCP 目录解压或复制到：

<Project>/Plugins/UnrealMCP

描述文件最终必须位于：

<Project>/Plugins/UnrealMCP/UnrealMCP.uplugin

打开项目，在 编辑 → 插件 中启用 Minimal MCP for Unreal Editor 和 Python Editor Script Plugin，然后重启编辑器。

引擎安装

要使插件可用于使用同一引擎构建的多个项目，请将其安装到：

C:/Program Files/Epic Games/UE_5.7/Engine/Plugins/Marketplace/UnrealMCP

可能需要管理员权限。项目本地安装通常更易于与项目一起进行版本管理，并且在开发时优先使用。

连接 Codex

Codex 桌面版、Codex CLI 和 IDE 扩展共享 MCP 配置。本地 stdio 服务器从配置的 command 启动。配置可以全局位于 ~/.codex/config.toml，或位于受信任项目内的 .codex/config.toml。请参阅 官方 Codex MCP 文档。

在 Windows TOML 路径中使用正斜杠：

[mcp_servers.unreal]
command = "C:/absolute/project/path/Plugins/UnrealMCP/Binaries/Win64/UnrealMCPGateway.exe"
startup_timeout_sec = 15
tool_timeout_sec = 3600

你也可以在 Codex 桌面版的 设置 → MCP 服务器 → 添加 → STDIO 下添加服务器。保存配置后，重启 Codex，并使用 /mcp 确认服务器已连接。

MCP 客户端只启动原生网关。它不会启动 Unreal Editor。在调用工具之前，请在 Unreal Editor 中打开目标项目。

端口和身份验证

工作器仅绑定到 127.0.0.1。以下环境变量由编辑器和网关独立读取：

对于身份验证，请在启动 Unreal Editor 和 Codex 之前设置相同的 token。不要提交该 token：

$env:UE_MCP_WORKER_TOKEN = '<a-long-random-token>'
$env:UE_MCP_WORKER_PORT = '18777'
& 'C:\Program Files\Epic Games\UE_5.7\Engine\Binaries\Win64\UnrealEditor.exe' 'C:\path\Project.uproject'

如果 Codex 不是从该 shell 启动的，请向其 MCP 服务器配置提供相同的值：

[mcp_servers.unreal]
command = "C:/absolute/project/path/Plugins/UnrealMCP/Binaries/Win64/UnrealMCPGateway.exe"
startup_timeout_sec = 15
tool_timeout_sec = 3600

[mcp_servers.unreal.env]
UE_MCP_WORKER_PORT = "18777"
UE_MCP_WORKER_TOKEN = "replace-with-the-same-token-used-by-the-editor"
UE_MCP_TIMEOUT_MS = "30000"

验证首次连接

让 MCP 客户端调用 unreal，参数如下：

{
  "action": "health"
}

健康响应的格式如下：

{
  "ok": true,
  "data": {
    "ok": true,
    "engine_version": "5.7.x-...",
    "is_game_thread": true,
    "python_loaded": true,
    "transport": "loopback-http"
  }
}

然后验证一次引擎读取：

{
  "action": "execute",
  "transaction": false,
  "commands": [
    {
      "kind": "python",
      "mode": "eval",
      "label": "engine-version",
      "code": "unreal.SystemLibrary.get_engine_version()"
    }
  ]
}

eval 计算一个 Python 表达式并返回其值。exec 执行语句或多行脚本。unreal 模块在插件的 Python 执行环境中可用。

单工具 API

unreal 使用操作判别模式，使 MCP 客户端只接收一个工具定义，同时保留发现、执行、健康检查和长时间运行的任务控制。

发现能力

在选择 UE API 之前，搜索独立的能力目录：

{
  "action": "discover",
  "query": "create and compile a blueprint",
  "limit": 5
}

使用 domain 指定精确域，例如 blueprint、asset、niagara、pcg、slate、umg 或 unlua。不带查询调用 discover 会返回最多所请求数量的目录条目。

执行有序批处理

execute 批处理最多接受 100 条 Python 或控制台命令。命令按顺序在 Game Thread 上运行。

{
  "action": "execute",
  "run": "sync",
  "transaction": true,
  "continue_on_error": false,
  "timeout_ms": 120000,
  "commands": [
    {
      "kind": "python",
      "mode": "exec",
      "label": "select-all-static-mesh-actors",
      "code": "subsystem = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)\nactors = subsystem.get_all_level_actors()\nsubsystem.set_selected_level_actors([a for a in actors if isinstance(a, unreal.StaticMeshActor)])"
    },
    {
      "kind": "console",
      "label": "show-fps",
      "command": "stat fps"
    }
  ]
}

• transaction 默认为 true，当整个批次成功时创建一条编辑器撤销记录。

• continue_on_error 默认为 false；启用后，后续命令仍会运行，但如果有任何命令失败，整体结果仍为失败。

• timeout_ms 接受 100 到 3600000 毫秒，并针对该调用覆盖 UE_MCP_TIMEOUT_MS。

• 每条命令都会返回 Python 结果和捕获到的 Python 日志，或控制台输出。

对于只读查询和不参与 Unreal 事务的 API，请使用 transaction: false。Unreal 事务是撤销记录，不是文件系统或源代码控制回滚。

运行和检查异步工作

对于较长的批次，请异步提交：

{
  "action": "execute",
  "run": "async",
  "timeout_ms": 3600000,
  "commands": [
    {
      "kind": "console",
      "command": "Automation RunTests Project"
    }
  ]
}

响应中包含 task_id。使用以下命令轮询或列出任务：

{ "action": "task", "command": "get", "task_id": "<uuid>" }

{ "action": "task", "command": "list" }

使用以下命令将任务标记为已取消：

{ "action": "task", "command": "cancel", "task_id": "<uuid>" }

任务状态保存在网关进程中，当 Codex 停止该进程时会丢失。取消是尽力而为：它会将跟踪标记为已取消，但已经分发到 Unreal Game Thread 的工作仍可能完成，并且不会回滚。

能力模型

该插件刻意避免提供数百个狭窄的包装工具。discover 提供配方和首选 API；execute 访问 UE 5.7 的反射 Python 表面、控制台命令、可选引擎插件以及项目特定的 API（如 UnLua）。

该目录映射了全部 21 个 UE 5.8 AllToolsets 组，包括编辑器/资产/蓝图工作、AI 和导航、动画、自动化、配置、对话、Data Registry、Dataflow、Game Features、Gameplay Tags 和 GAS、Niagara、PCG、物理、插件、语义搜索、Slate、StateTree、UMG 和 World Conditions。

覆盖范围指路由和机制覆盖，并非声称仅存在于 UE 5.8 的类在 UE 5.7 中存在。可选工作流需要启用相应的引擎或项目插件。相关理由和五次最小化过程记录在 工具最小化 中。

从源码构建

要求：

• Unreal Engine 5.7 源码/构建安装。脚本默认使用 C:\Program Files\Epic Games\UE_5.7。

• UE 5.7 支持的 Visual Studio C++ 工具链。

• PowerShell。

• Node.js 20+ 仅用于可选的 MCP 协议测试；Node 不是产品运行时依赖。

就地编译原生网关：

.\scripts\build-native-gateway.ps1

将完整插件包构建到新目录：

.\scripts\build-plugin.ps1 -OutputDirectory 'C:\Temp\UnrealMCP-Package'

创建单顶层目录的 Fab ZIP：

.\scripts\build-fab-package.ps1 -OutputFile '.\artifacts\UnrealMCP-0.2.0-UE5.7-Win64.zip'

打包的插件包含描述文件、源码、配置、资源、原生 DLL 和 EXE、许可证声明、英文和简体中文 README 以及设计文档。Fab ZIP 恰好包含一个顶层 UnrealMCP/ 目录，并排除 Intermediate、PDB 文件、Node 包和开发测试项目。

每个引擎版本和平台都需要自己经过编译和测试的二进制包。当前描述文件仅面向 Win64。

测试

运行元数据和原生现代/旧版 MCP 集成测试：

npm install
npm test

运行完整的原生 stdio 网关 → 回环工作器 → Game Thread → UE Python 路径：

.\scripts\build-native-gateway.ps1
.\scripts\test-worker-e2e.ps1

端到端测试会在独立端口上以无头模式启动随附的 UE57MCPTest.uproject，并在验证后将其关闭。如果所选端口被占用，请关闭无关的自动化测试实例。

故障排查

网关仅将 MCP 协议消息写入 stdout，将诊断信息写入 stderr。插件启动、绑定、授权和执行错误会显示在 Unreal Output Log 的 LogUnrealMCP 下。

安全与操作限制

execute 有意允许任意的 Unreal Python 和控制台命令。请将对本工具的访问视为允许智能体操作已打开的编辑器项目。

• 工作进程仅绑定到回环地址；它不是远程网络服务。

• Bearer 认证是可选的，但在共享机器上建议启用。

• 请求体限制为 4 MiB，批次限制为 100 条命令。

• UObject 和编辑器访问在游戏线程上运行。

• 请勿将机密信息放在工具参数、项目文件、日志或已提交的 Codex 配置中。

• 对于破坏性的资产、配置、插件和文件系统操作，请使用源代码控制。

仓库结构

分发说明

生成的 ZIP 包结构为单个可安装的 UE Code Plugin，适合 Fab 技术审查。Marketplace 发布仍需卖家/上架元数据和视觉资产，如插件图标和截图，以及一个针对每个宣传的引擎版本和平台测试过的包。

许可证详情见 LICENSE，第三方声明见 THIRD_PARTY_NOTICES.md。其他设计说明：架构、能力覆盖 和 工具最小化。

如果这个项目对您有帮助，请考虑给它一个 Star ⭐