unreal-mcp-ue4

unreal-mcp-ue4

面向 UE4.27.2 的 MCP 服务，通过 Unreal Python Remote Execution 与 Unreal Engine 通信

unreal-mcp-ue4 最初源自 runreal/unreal-mcp 的核心思路和早期工作流形态，但此后已针对 Unreal Engine 4.27.2 进行了大量重构，并扩展出许多新工具、UE4 专属兼容层、文档和冒烟测试覆盖。至此，最初的灵感依然可见，但公开接口和日常行为已大幅不同，并且以 UE4 优先。

本次移植以及后续的工具、文档和冒烟测试工作是在 OpenAI Codex 的协助下开发的。

本项目仍在积极开发中，因此仍可能出现 bug、粗糙之处以及 UE4.27 特有的限制。

已发布包：unreal-mcp-ue4
注册表名称：io.github.conaman/unreal-mcp-ue4

概述

• 无需本仓库提供的自定义 Unreal C++ 插件。
• 服务通过 Unreal 内置的 Python Remote Execution 通道与编辑器通信。
• 工具接口按细粒度工具和更高层的工具命名空间组织。
• 不会重新引入仅限 UE5 的编辑器脚本功能；UE4.27 安全的操作可正常工作，而不可靠的图表或绑定流程要么从 MCP 接口中排除，要么返回明确消息，而不是静默失败。

起源

• 最初的灵感和起点：runreal/unreal-mcp
• 当前代码库经历了大量以 UE4.27 为重点的重构、架构变更和工具扩展。
• 实际上，共同的想法仍然可见，但实现、范围和支持的工作流如今反映的是一个独立的、UE4 优先的项目。
• Unreal Python API 参考：Unreal Engine Python API 4.27

安全性

• 这不是 Epic Games 的官方项目。
• 任何已连接的 MCP 客户端都可以检查并修改你打开的 Unreal Editor 会话。
• 请先使用一次性测试项目，尤其是在使用资产或世界生成工具时。

要求

• Unreal Engine 4.27.2
• Node.js 18+
• npm
• MCP 客户端，例如 Codex、Claude Code、Claude Desktop、Cursor，或受支持 IDE 中的 GitHub Copilot

MCP 客户端设置

这是最重要的设置步骤：你的 MCP 客户端必须知道如何启动 unreal-mcp-ue4。

1. 安装服务

推荐的全局安装：

npm install -g unreal-mcp-ue4

全局安装后，在客户端配置中使用已发布的 unreal-mcp-ue4 二进制文件。

使用 npx 一次性调用：

npx unreal-mcp-ue4

本地源码检出：

git clone https://github.com/conaman/unreal-mcp-ue4.git
cd unreal-mcp-ue4
npm install
npm run build

成功构建后应生成 dist/bin.js、dist/index.js 和 dist/editor/tools.js。在下面的本地源码检出示例中使用 dist/bin.js 路径。

2. 在客户端中注册服务

如果你使用 npm install -g unreal-mcp-ue4 安装，请使用全局示例。如果你从克隆的仓库进行开发，请使用本地源码检出示例。

Claude

全局 npm 安装：

claude mcp add --scope user unreal-mcp-ue4 -- unreal-mcp-ue4

本地源码检出：

claude mcp add --scope user unreal-mcp-ue4 -- node /absolute/path/to/unreal-mcp-ue4/dist/bin.js

Codex

全局 npm 安装：

codex mcp add unreal-ue4 -- unreal-mcp-ue4

本地源码检出：

codex mcp add unreal-ue4 -- node /absolute/path/to/unreal-mcp-ue4/dist/bin.js

GitHub Copilot

创建或更新 .vscode/mcp.json。

全局 npm 安装：

{
  "servers": {
    "unreal-ue4": {
      "command": "unreal-mcp-ue4",
      "args": []
    }
  }
}

本地源码检出：

{
  "servers": {
    "unreal-ue4": {
      "command": "node",
      "args": [
        "/absolute/path/to/unreal-mcp-ue4/dist/bin.js"
      ]
    }
  }
}

然后从 MCP 配置界面启动服务，并确认 unreal-ue4 出现在工具选择器中。

Copilot 官方文档：

• 使用 MCP 服务扩展 GitHub Copilot Chat
• 关于 GitHub Copilot 中的 Model Context Protocol

3. 启用 Unreal Editor 远程执行

本仓库不附带自己的 Unreal 插件。它依赖必须在你的 UE4.27.2 项目中启用的内置编辑器功能。

在 Unreal Editor 中：

1. 打开目标 UE4.27.2 项目。
2. 前往 Edit -> Plugins。
3. 启用 Python Editor Script Plugin。
4. 启用 Editor Scripting Utilities。
5. 如果你想使用高级 manage_sequence 操作（例如 actor 绑定、轨道或关键帧编辑、镜头切换、播放范围以及速度轨道分析），请启用 SequencerScripting。
6. 如果提示，请重启编辑器。
7. 前往 Edit -> Project Settings -> Python。
8. 启用 Enable Remote Execution。
9. 如果需要，再次重启编辑器。

说明：

• UMG 工具可与 Unreal Editor 已内置的编辑器模块配合使用。无需从本仓库安装额外的 UMG 插件。
• 在使用 MCP 服务或运行测试时，请保持目标 Unreal 项目处于打开状态。
• 如果你更改了插件或 Python 设置，请在再次测试前重启编辑器。

用法

接口模型

• 优先将 manage_* 命名空间工具作为主要 MCP 接口。
• 命名空间工具现在通过 MCP 暴露特定于 action 的输入 schema，因此客户端可以发现每个 action 预期的 params 键，而不必仅依赖反复试错。
• 将 manage_editor.project_info 视为规范的项目摘要入口点。
• 将 manage_editor.map_info 和 manage_level.world_outliner 视为规范的 map 和 level 读取入口点。
• 仅将直接工具用于少量底层原语，例如 Unreal 会话路径发现以及 actor 创建、更新或删除流程。
• 将 manage_editor.run_python 作为调试、快速原型开发以及尚未包装为稳定工具的 UE4.27 API 缺口的安全出口。

推荐的首次运行流程

1. 打开你的 UE4.27.2 项目，并等待编辑器完成加载。
2. 确保已启用所需插件和 Enable Remote Execution。
3. 使用 npm install -g unreal-mcp-ue4 全局安装 MCP 服务，或使用 npm run build 构建本地检出。
4. 启动你的 MCP 客户端，或在已引用此服务的客户端中打开新会话。
5. 先运行一个小的只读命令。

有用的首批命令：

• unreal-mcp-ue4 --version 用于打印 MCP 服务包版本，而不启动 stdio 传输。
• manage_editor 配合 action: "project_info"
• manage_editor 配合 action: "map_info"
• manage_level 配合 action: "world_outliner"
• manage_tools 配合 action: "list_namespaces"

有用的首批自然语言请求：

• Get project info from the unreal-ue4 server.
• List the actors in the current level.
• Spawn a StaticMeshActor named TestCube at 0,0,100.

该服务能做什么

• 从打开的编辑器读取项目、map、资产和 actor 信息。
• 在当前 level 中生成、检查、移动和删除 actor。
• 搜索资产并检查引用或元数据。
• 创建常见的 UE4 数据资产，例如 DataAsset 和 StringTable 资产。
• 在 UE4.27 Python 暴露必要编辑器 API 的情况下，创建和编辑 Blueprint 资产。
• 使用对 UE4.27 安全的 UMG 辅助工具创建和编辑 Widget Blueprint 树。
• 运行分组工具命名空间，这些命名空间通过 action 和 params 进行分发。

测试

无 Unreal 冒烟测试

当你想要在不启动 Unreal Editor 的情况下验证 MCP 启动、工具发现、命名空间操作 schema 以及特定操作的参数校验时，请使用此测试。

npm run test:no-unreal

快速冒烟测试

该冒烟测试会构建服务、启动其自身的本地 MCP 服务进程、连接到已在运行的 Unreal Editor，并运行一套确定性的验证流程。在此测试之前，你无需手动启动单独的 MCP 服务。

npm run test:e2e

这会检查：

• MCP 服务启动
• 工具发现
• 项目信息、地图信息和世界大纲视图读取
• 源代码管理提供程序与状态读取
• 直接工具 Actor 的创建、更新和删除
• 命名空间层 Actor 的生成、搜索、变换、检查和删除
• 工具命名空间发现，以及针对源代码管理和 Actor 控制的命名空间层分发

包含资产的冒烟测试

npm run test:e2e -- --with-assets

这额外增加了：

• Blueprint 创建
• Blueprint 组件编辑
• Blueprint 网格体分配
• Blueprint 编译
• DataAsset 创建
• DataAsset 元数据回读
• StringTable 创建
• 纹理导入与元数据回读
• Widget Blueprint 创建
• TextBlock 与 Button 插入
• 高级 CanvasPanel 与子控件添加、移动和移除流程
• 清理 /Game/MCP/Tests 下的临时资产

实用选项：

• npm run test:e2e -- --with-assets --keep-assets 会保留生成的测试资产，以便你在运行结束后于内容浏览器中检查它们。
• npm run test:e2e -- --skip-namespace 会跳过冒烟运行中的命名空间分发部分。
• npm run test:e2e -- --verbose 会在运行期间打印 MCP 服务的 stderr。
• npm run test:e2e -- --help 会打印运行器选项，而不会重新构建服务。

Windows 测试命令

在仓库文件夹中打开 PowerShell：

cd C:\dev\unreal-mcp-ue4
npm install
npm run test:no-unreal
npm run test:e2e
npm run test:e2e -- --with-assets

成功的样子

• 控制台会为每个测试步骤打印 [PASS]。
• Actor 测试会通过直接工具和命名空间两种表面，在编辑器中可见地创建并随后移除临时 Actor。
• 包含资产的测试会在 /Game/MCP/Tests 下创建临时 Blueprint、DataAsset、StringTable、Texture 和 Widget Blueprint 资产，然后在退出前移除它们，除非使用了 --keep-assets。

推荐的测试工作流

1. 从 npm run test:no-unreal 开始。
2. 如果通过，运行 npm run test:e2e。
3. 如果由编辑器支持的冒烟测试通过，运行 npm run test:e2e -- --with-assets。
4. 所有冒烟测试通过后，从你真实的 MCP 客户端试用一次服务。
5. 在将服务指向生产内容之前，先使用一个单独的 Unreal 测试项目。

发布到 npm

该包以公共包的形式发布到 npm。

项目版本格式在所有地方统一为兼容 semver 的日期形式 YYYY.M.D-N。例如，2026.5.8-1 遵循此格式。

推荐的维护者流程：

1. 更新项目版本。
2. 运行发布预检：

npm run publish:check

3. 如果你有可用的运行中的 UE4.27 编辑器测试环境，也请运行：

npm run test:e2e -- --with-assets --skip-build

4. 发布：

npm publish --tag latest

注意：

• prepack 会运行 npm run build，因此发布的 tarball 始终使用全新的 dist。
• npm run publish:check 会验证类型检查、重新构建包，并运行 npm pack --dry-run，以便你在发布前检查确切的 tarball 内容。
• 由于统一的日期版本使用 semver 预发布后缀，请在发布时使用显式的 dist-tag，例如 latest。

故障排查

Remote node is not available

• 在运行 MCP 客户端或冒烟测试之前，请确保 Unreal Editor 已完全打开。
• 验证 Python Editor Script Plugin 已启用。
• 验证 Editor Scripting Utilities 已启用。
• 验证项目设置中的 Enable Remote Execution 已启用。
• 更改上述任何一项后，请重启 Unreal Editor。

Windows 上的连接或发现问题

• 允许 UnrealEditor.exe 和 node.exe 通过 Windows Defender 防火墙。
• 该服务在 239.0.0.1:6766 上使用 UDP 多播发现，并在端口 6776 上打开命令通道。
• 默认情况下，命令绑定地址是机器上找到的第一个非内部 IPv4 地址。如果 Unreal 无法发现或连接到 MCP 进程，可用 UNREAL_MCP_BIND_ADDRESS 或 UNREAL_MCP_COMMAND_ADDRESS 覆盖它。
• 如果你的客户端配置使用 JSON，请转义反斜杠或改用正斜杠。

客户端启动了，但找不到 unreal-mcp-ue4 或 node

• 对于推荐的全局安装，请确保 npm 全局二进制目录位于 MCP 客户端的 PATH 中。
• 如果你的客户端无法继承该 PATH，请使用全局 unreal-mcp-ue4 可执行文件的绝对路径。
• 如果你使用的是源码开发配置，请使用 node 或 node.exe 的绝对路径，而不是依赖 PATH。

部分 Blueprint 图表或 UMG 绑定命令不可用

• 在此分支中，Widget Blueprint 创建和常见的 widget 树编辑可以正常工作；UMG 的主要缺口是委托绑定辅助工具和依赖运行时的视口流程。
• Blueprint 资源创建、组件编辑、编译和高层资源摘要可以正常工作；图表检查、图表引脚连线以及变量或函数元数据辅助工具被有意排除，因为原版 UE4.27 Python 无法可靠地暴露所需的 Blueprint 元数据。
• 可靠性不足以保留在 MCP 表面中的能力领域列在工具部分的 Excluded Capability Areas 下。

注意事项和限制

• 世界构建和结构生成工具使用基于引擎基本形状资源的 UE4.27 友好预设构建器。
• 常见的 UMG widget 树编辑可与原生 PanelWidget 父级一起工作，但委托绑定辅助工具在原版 UE4.27 Python 中仍然不可用。
• UMG 绝对定位在 UE4.27 中针对 CanvasPanel 槽位。当 Widget Blueprint 具有非 Canvas 根，但需要 CanvasPanel 风格的定位时，请使用 manage_widget.ensure_canvas_root。
• 目前不处理直接重新设置当前根 widget 的父级以及编辑命名槽位内容。
• Blueprint 资源和组件编辑可以正常工作，但在原版 UE4.27 Python 环境中，Blueprint 图表检查、引脚连线和变量或函数元数据检查被排除。
• 工具表面同时包含细粒度工具和基于操作的工具命名空间，以便不同的 MCP 客户端可以在不同的抽象级别上工作。

下面的工具列表在构建期间从 TypeScript 工具目录生成。

可用工具

注释会在重要时指出重要要求或 UE4.27 限制。空注释意味着除了正常编辑器设置之外没有其他注意事项。

推荐的公共表面是 manage_* 命名空间层。优先使用 manage_editor.project_info、manage_editor.map_info 和 manage_level.world_outliner 作为规范读取入口点，并将小型直接工具集视为用于路径发现和 actor CRUD 的低级原语。

编辑器会话信息

工具	描述	注释
get_unreal_engine_path	从连接的编辑器会话中获取活动的 Unreal Engine 根路径
get_unreal_project_path	从连接的编辑器会话中获取活动的 Unreal 项目文件路径
get_unreal_version	从连接的编辑器会话中获取活动的 Unreal Engine 版本字符串

### 核心直接工具

工具	描述	备注
editor_create_object	在世界中创建新的对象/Actor
editor_update_object	更新世界中已有的对象/Actor
editor_delete_object	从世界中删除对象/Actor

核心工具命名空间

工具	描述	备注
manage_asset	资产工具命名空间，用于列出、搜索、检查、导出、验证、复制、重命名、移动、删除、保存以及文件夹管理操作。
manage_actor	Actor 工具命名空间，用于列出、搜索、生成、删除、变换和检查关卡 Actor。
manage_editor	编辑器工具命名空间，用于 run_python、console_command、project_info、map_info、world_outliner、is_pie_running、start_pie、stop_pie、screenshot 和 move_camera 操作。	project_info、map_info、world_outliner、start_pie、stop_pie、is_pie_running、console_command 和 run_python 的标准命名空间。
manage_level	关卡工具命名空间，用于地图检查、Actor 列出、世界大纲检查以及预设结构创建操作。
manage_system	系统工具命名空间，用于控制台命令和资产验证操作。	用于控制台和验证辅助功能的精简命名空间；请使用 manage_editor 进行标准的项目和地图检查。
manage_inspection	检查工具命名空间，用于资产、Actor、地图和基本蓝图摘要操作。	处理资产、Actor 和地图检查；在原版 UE4.27 Python 中，蓝图检查仅限于高层级的资产摘要。
manage_tools	工具命名空间注册表，用于列出已注册的工具命名空间并描述支持的操作。请将其作为命名空间优先的 MCP 接口的发现入口点。
manage_source_control	源代码管理工具命名空间，用于提供程序检查以及文件或包的源代码管理操作。	provider_info 可广泛使用，但文件和包操作需要配置并可用的 Unreal 源代码管理提供程序。

### 世界与环境工具命名空间

工具	描述	说明
manage_lighting	光照工具命名空间，用于生成常见光源 Actor、对其进行变换，以及检查关卡光照状态。
manage_level_structure	关卡结构工具命名空间，用于预设的城镇、房屋、宅邸、塔楼、墙壁、桥梁和堡垒建造操作。
manage_volumes	体积工具命名空间，用于生成常见引擎体积并应用删除或变换操作。
manage_navigation	导航工具命名空间，用于生成导航体积和导航代理，以及基本的贴图检查操作。
manage_environment	环境构建工具命名空间，用于预设的城镇、拱门、楼梯、金字塔和迷宫生成操作。
manage_splines	样条线工具命名空间，用于生成样条线宿主 Actor 或 Blueprint，然后对其进行变换或删除。
manage_geometry	几何体工具命名空间，用于墙壁、拱门、楼梯和金字塔预设建造操作。
manage_effect	效果工具命名空间，用于生成调试形状 Actor、为其指定材质、着色以及删除。

### 内容与创作工具命名空间

工具	描述	备注
manage_skeleton	Skeleton 工具命名空间，用于搜索 Skeleton 与 SkeletalMesh 资源并查看其元数据。
manage_material	Material 工具命名空间，用于列出材质、将其应用到 Actor 或 Blueprint，并通过材质实例为其着色。
manage_texture	Texture 工具命名空间，用于搜索纹理资源、将图像文件导入为纹理，并读取其资源元数据。	import_texture 需要本地图像文件路径，且该路径可从运行 Unreal Editor 会话的机器访问。
manage_data	Data 工具命名空间，用于搜索数据资源、创建常见数据容器，并查看其资源元数据。
manage_blueprint	Blueprint 工具命名空间，用于 Blueprint 创建、组件编辑、编译以及基本的 Blueprint 摘要操作。	Blueprint 资源与组件编辑可用；在原生 UE4.27 Python 中，图表查看、引脚连线以及变量或函数元数据辅助功能不在 MCP 暴露范围内。
manage_sequence	Sequence 工具命名空间，用于创建、搜索、查看和编辑 LevelSequence 资源，包括绑定、轨道、区段、关键帧、摄像机切换、播放范围以及速度轨道时间计算。	高级绑定、轨道、区段、关键帧、摄像机切换、播放范围以及速度轨道分析操作需要在目标项目中启用 UE4.27 SequencerScripting 插件。
manage_audio	Audio 工具命名空间，用于导入音频文件、搜索音频资源，并查看其资源元数据。
manage_widget	Widget 工具命名空间，用于 UMG Blueprint 创建、控件树查看、控件树编辑、CanvasPanel 根节点规范化以及视口生成操作。使用 inspect_tree 验证设计器内容，使用 add_child_widget 进行嵌套布局工作，并在需要绝对 CanvasPanel 定位时使用 ensure_canvas_root。	create_widget_blueprint、inspect_tree、add_text_block、add_button 和 ensure_canvas_root 可用；常规嵌套布局请使用 add_child_widget，如果根节点是其他面板，则在 CanvasPanel 定位或调整尺寸前使用 ensure_canvas_root。add_to_viewport 需要 PIE；start_pie_if_needed 可以请求 PIE，且可能需要重试。

### 玩法与系统工具命名空间

工具	描述	备注
manage_animation_physics	动画与物理工具命名空间，用于物理 Blueprint 生成、Blueprint 物理设置以及 Blueprint 编译操作。
manage_input	输入工具命名空间，用于创建经典 UE4 输入映射。	专注于经典 UE4 输入映射的编写；如需规范的项目摘要，请使用 manage_editor.project_info。
manage_behavior_tree	行为树工具命名空间，用于创建、搜索和检查 BehaviorTree 资产。	专注于 BehaviorTree 资产的发现与检查；如需规范的项目摘要，请使用 manage_editor.project_info。
manage_gas	GAS 工具命名空间，用于搜索与玩法能力相关的资产并检查其资产元数据。

已排除的能力领域

在此 UE4.27 移植版中，这些能力领域有意不通过 MCP 接口暴露，因为它们在当前 Python 环境中会稳定失败，并且在原生桥接存在之前只会增加提示词或上下文开销。

能力领域	对 MCP 接口的影响	排除原因
Blueprint 事件图表事件插入	相关的事件节点和输入操作辅助工具已从 MCP 接口中排除。	当前 UE4.27 Python 环境无法暴露可靠的事件图表访问或 K2 事件引用设置。
Blueprint 图表检查与节点搜索	图表分析、图表检查和节点搜索辅助工具已从 MCP 接口中排除。	当前 UE4.27 Python 环境无法足够可靠地暴露 UbergraphPages 或 FunctionGraphs 等 Blueprint 图表数组，以进行确定性检查。
底层 Blueprint 图表节点创建	通用图表节点辅助工具以及相关的 self 或组件引用插入辅助工具已从 MCP 接口中排除。	当前 UE4.27 Python 环境无法暴露稳定的底层图表节点创建或成员引用连接。
Blueprint 函数调用节点编写	依赖编辑器图表成员引用设置的函数节点辅助工具已从 MCP 接口中排除。	当前 UE4.27 Python 环境无法暴露可靠的函数调用节点引用设置。
Blueprint 变量与函数元数据检查	变量详情和函数详情辅助工具已从 MCP 接口中排除。	当前 UE4.27 Python 环境无法足够可靠地暴露 NewVariables 或 FunctionGraphs，以进行确定性检查。
Blueprint 变量编写	变量创建辅助工具已从 MCP 接口中排除。	当前 UE4.27 Python 环境中未暴露 BPVariableDescription 和 EdGraphPinType。
UMG 委托绑定编写	控件事件绑定和文本绑定辅助工具已从 MCP 接口中排除。	当前 UE4.27 Python 环境中未暴露 DelegateEditorBinding。

License

Licensed under the MIT License。