Unreal MCP Ue4

非放射性mcp-ue4

UE4.27.2使用虚幻Python远程执行的虚幻引擎专用MCP服务器

](https://www.npmjs.com/package/unreal-mcp-ue4)  ](https://github.com/conaman/unreal-mcp-ue4/releases/latest)

unreal-mcp-ue4 从核心思想和早期工作流形态入手 运行真实/不真实mcp，但此后它已针对虚幻引擎4.27.2进行了大量重构，并扩展了许多新工具、UE4特定的兼容性层、文档和烟雾覆盖。此时，最初的灵感仍然存在，但公众的表面和日常行为与UE4有很大不同。

该端口和后续工具、文档和烟雾测试工作是在OpenAI Codex的协助下开发的。

该项目仍在积极开发中，因此错误、粗糙边缘和UE4.27特定的限制可能仍然会出现。 已发布包： unreal-mcp-ue4\ 注册表名称： io.github.conaman/unreal-mcp-ue4

概述

• 不需要此存储库中的自定义虚幻C++插件。
• 服务器通过虚幻内置的Python远程执行路径与编辑器进行对话。
• 工具表面被组织成粒度工具和更高级别的工具名称空间。
• 仅UE5的编辑器脚本功能没有重新引入；UE4.27-safe操作正常工作，而不可靠的图或绑定流要么被排除在MCP表面之外，要么返回一条明确的消息，而不是默默地失败。

起源

• 原创灵感与出发点： 运行真实/不真实mcp
• 当前的代码库已经经历了广泛的以UE4.27为重点的重构、架构更改和工具扩展。
• 在实践中，共享的想法仍然可见，但实现、范围和支持的工作流现在反映了一个单独的UE4优先项目。
• 虚幻Python API参考： 虚幻引擎Python API 4.27

安全

• 这不是Epic Games的官方项目。
• 任何连接的MCP客户端都可以检查和修改您打开的虚幻编辑器会话。
• 首先使用一次性测试项目，尤其是在尝试资产或世界生成工具时。

需求

• 虚幻引擎 4.27.2
• Node.js 18+
• npm
• 支持IDE中的MCP客户端，如Codex、Claude Code、Claude Desktop、Cursor或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。当您从克隆的存储库进行开发时，请使用本地源代码签出示例。

克劳德

全局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

法典

全局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配置UI启动服务器，并验证 unreal-ue4 出现在工具选择器中。

Copilot官方文件：

3.启用虚幻编辑器远程执行

此存储库不提供自己的虚幻插件。相反，它取决于必须在UE4.27.2项目中启用的内置编辑器功能。

在虚幻编辑器中：

1. 打开目标UE4.27.2项目。
2. 首选 Edit -> Plugins.
3. 启用 Python Editor Script Plugin.
4. 启用 Editor Scripting Utilities.
5. 如果出现提示，请重新启动编辑器。
6. 首选 Edit -> Project Settings -> Python.
7. 启用 Enable Remote Execution.
8. 如果需要，请重新启动编辑器。

笔记：

• UMG工具可与虚幻编辑器附带的编辑器模块配合使用。此存储库中没有额外的UMG插件可供安装。
• 在使用MCP服务器或运行测试时，保持目标虚幻项目打开。
• 如果您更改了插件或Python设置，请在再次测试之前重新启动编辑器。

用法

接口模型

• 更喜欢 manage_* 名称空间工具作为主MCP表面。
• 命名空间工具现在通过MCP公开特定于操作的输入模式，因此客户端可以发现预期的 params 每个操作都有密钥，而不仅仅依赖于试错。
• 对待 manage_editor.project_info 作为规范的项目摘要入口点。
• 对待 manage_editor.map_info 和 manage_level.world_outliner 作为规范地图和关卡阅读入口点。
• 仅对一小部分低级原语使用直接工具，如虚幻会话路径发现和参与者创建、更新或删除流。
• 使用 manage_editor.run_python 作为调试、快速原型设计和UE4.27 API间隙的逃生通道，这些间隙尚未作为稳定工具封装。

推荐的首次运行流程

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

有用的第一个命令：

• unreal-mcp-ue4 --version 在不启动stdio传输的情况下打印MCP服务器包版本。
• 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.

服务器可以做什么

• 从打开的编辑器中读取项目、地图、资产和参与者信息。
• 生成、检查、移动和删除当前级别中的参与者。
• 搜索资产并检查引用或元数据。
• 创建通用UE4数据资产，例如 DataAsset 和 StringTable 资产。
• 创建和编辑蓝图资产，其中UE4.27 Python公开了必要的编辑器API。
• 使用UE4.27-safe UMG助手创建和编辑小部件蓝图树。
• 运行通过调度的分组工具命名空间 action 和 params.

测试

无虚幻烟雾测试

当您想在不启动虚幻编辑器的情况下验证MCP启动、工具发现、命名空间操作模式和特定于操作的参数验证时，请使用此选项。

npm run test:no-unreal

快速烟雾测试

冒烟测试构建服务器，启动自己的本地MCP服务器进程，连接到已经运行的虚幻编辑器，并运行确定性验证流。在此测试之前，您不需要手动启动单独的MCP服务器。

npm run test:e2e

这将检查：

• MCP服务器启动
• 工具发现
• 项目信息、地图信息和世界大纲阅读
• 源代码管理提供程序和状态读取
• 直接工具参与者创建、更新和删除
• 名称空间层参与者生成、搜索、转换、检查和删除
• 用于源代码控制和参与者控制的工具命名空间发现和命名空间层调度

含资产的烟雾测试

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

这增加了：

• 蓝图创建
• 蓝图组件编辑
• 蓝图网格分配
• 蓝图编译
• 数据资产创建
• 数据资产元数据回读
• 创建字符串表
• 纹理导入和元数据回读
• 小部件蓝图创建
• 文本块和按钮插入
• 高级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。
• 包含资产的测试在以下位置创建临时Blueprint、DataAsset、StringTable、Texture和Widget Blueprint资产 /Game/MCP/Tests 然后在退出前将其删除，除非 --keep-assets 使用。

推荐的测试工作流程

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

发布到npm

该包作为公共包发布到npm。

项目版本格式在任何地方都统一为semver兼容的日期格式 YYYY.M.D-N例如， 2026.5.8-1 遵循这种格式。

推荐的维护流程：

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

npm run publish:check

1. 如果您有正在运行的UE4.27编辑器测试环境可用，请同时运行：

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

1. 发布：

npm publish --tag latest

笔记：

• prepack 跑 npm run build，所以出版的tarball总是使用新鲜的 dist.
• npm run publish:check 验证类型检查，重建包，并运行 npm pack --dry-run 因此，您可以在发布之前检查确切的tarball内容。
• 因为统一日期版本使用semver预发布后缀，所以使用显式dist标签发布，例如 latest.

故障排除

Remote node is not available

• 在运行MCP客户端或冒烟测试之前，请确保虚幻编辑器完全打开。
• 核实一下 Python Editor Script Plugin 已启用。
• 核实一下 Editor Scripting Utilities 已启用。
• 核实一下 Enable Remote Execution 在项目设置中启用。
• 更改上述任何内容后重新启动虚幻编辑器。

Windows上的连接或发现问题

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

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

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

某些蓝图图或UMG绑定命令不可用

• 本次分叉中的Widget蓝图创建和常用Widget树编辑工作；主要的UMG间隙是委托绑定助手和依赖于运行时的视口流。
• 蓝图资产创建、组件编辑、编译和高级资产汇总工作；图检查、图引脚连接和变量或函数元数据助手被有意排除在外，因为UE4.27 Python没有可靠地公开所需的蓝图元数据。
• MCP表面不可靠的能力区域如下 Excluded Capability Areas 在工具部分。

注意事项和限制

• 世界建筑和结构生成工具使用基于引擎基本形状资产的UE4.27友好的预设构建器。
• 通用UMG小部件树编辑与本机兼容 PanelWidget 父对象，但委托绑定助手在UE4.27 Python中仍然不可用。
• UMG绝对定位目标 CanvasPanel UE4.27中的插槽。使用 manage_widget.ensure_canvas_root 当Widget蓝图具有非Canvas根但需要CanvasPanel样式定位时。
• 当前不处理直接重新分配当前根小部件和编辑命名槽内容。
• 蓝图资产和组件编辑工作，但蓝图图检查、引脚接线和变量或函数元数据检查不包括在UE4.27 Python环境中。
• 工具界面包括粒度工具和基于动作的工具名称空间，因此不同的MCP客户端可以在不同的抽象级别上工作。

下面的工具列表是在构建过程中从TypeScript工具目录生成的。

可用工具

注释指出了重要要求或UE4.27的限制。空注释意味着除了正常的编辑器设置外，没有其他警告。

建议的公共表面是 manage_* 命名空间层。更喜欢 manage_editor.project_info, manage_editor.map_info，以及 manage_level.world_outliner 将小型直接工具集视为路径发现和参与者CRUD的低级原语。

编辑器会话信息

Tool Description Notes

get_unreal_engine_path Get the active Unreal Engine root path from the connected editor session

get_unreal_project_path Get the active Unreal project file path from the connected editor session

get_unreal_version Get the active Unreal Engine version string from the connected editor session

核心直接工具

Tool Description Notes

editor_create_object Create a new object/actor in the world

editor_update_object Update an existing object/actor in the world

editor_delete_object Delete an object/actor from the world

核心工具命名空间

Tool Description Notes

manage_asset Asset tool namespace for listing, searching, inspecting, exporting, validating, duplicating, renaming, moving, deleting, saving, and folder-management actions.

manage_actor Actor tool namespace for listing, searching, spawning, deleting, transforming, and inspecting level actors.

manage_editor Editor tool namespace for run_python, console_command, project_info, map_info, world_outliner, is_pie_running, start_pie, stop_pie, screenshot, and move_camera actions. Canonical namespace for project_info, map_info, world_outliner, start_pie, stop_pie, is_pie_running, console_command, and run_python.

manage_level Level tool namespace for map inspection, actor listing, world outliner inspection, and preset structure creation actions.

manage_system System tool namespace for console commands and asset validation actions. Slim namespace for console and validation helpers; use manage_editor for canonical project and map inspection.

manage_inspection Inspection tool namespace for asset, actor, map, and basic Blueprint summary actions. Asset, actor, and map inspection work; Blueprint inspection is limited to high-level asset summaries in stock UE4.27 Python.

manage_tools Tool-namespace registry for listing registered tool namespaces and describing supported actions. Use this as the discovery entry point for the namespace-first MCP surface.

manage_source_control Source-control tool namespace for provider inspection and file or package source-control operations. provider_info works broadly, but file and package operations require a configured and available Unreal source-control provider.

世界和环境工具命名空间

Tool Description Notes

manage_lighting Lighting tool namespace for spawning common light actors, transforming them, and inspecting level lighting state.

manage_level_structure Level-structure tool namespace for preset town, house, mansion, tower, wall, bridge, and fortress construction actions.

manage_volumes Volume tool namespace for spawning common engine volumes and applying delete or transform actions.

manage_navigation Navigation tool namespace for spawning navigation volumes and proxies plus basic map inspection actions.

manage_environment Environment-building tool namespace for preset town, arch, staircase, pyramid, and maze generation actions.

manage_splines Spline tool namespace for spawning a spline-host actor or Blueprint and then transforming or deleting it.

manage_geometry Geometry tool namespace for wall, arch, staircase, and pyramid preset construction actions.

manage_effect Effects tool namespace for spawning debug-shape actors, assigning materials, tinting them, and deleting them.

内容和创作工具命名空间

Tool Description Notes

manage_skeleton Skeleton tool namespace for searching Skeleton and SkeletalMesh assets and inspecting their metadata.

manage_material Material tool namespace for listing materials, applying them to actors or Blueprints, and tinting them with material instances.

manage_texture Texture tool namespace for searching texture assets, importing image files as textures, and reading their asset metadata. import_texture requires a local image file path that is accessible from the machine running the Unreal Editor session.

manage_data Data tool namespace for searching data assets, creating common data containers, and inspecting their asset metadata.

manage_blueprint Blueprint tool namespace for Blueprint creation, component editing, compilation, and basic Blueprint summary actions. Blueprint asset and component edits work; graph inspection, pin wiring, and variable or function metadata helpers are excluded from the MCP surface in stock UE4.27 Python.

manage_sequence Sequence tool namespace for creating, searching, and inspecting LevelSequence assets.

manage_audio Audio tool namespace for importing audio files, searching audio assets, and inspecting their asset metadata.

manage_widget Widget tool namespace for UMG Blueprint creation, widget-tree inspection, widget-tree edits, CanvasPanel root normalization, and viewport spawning actions. Use inspect_tree to verify designer contents, add_child_widget for nested layout work, and ensure_canvas_root when absolute CanvasPanel positioning is required. create_widget_blueprint, inspect_tree, add_text_block, add_button, and ensure_canvas_root work; use add_child_widget for normal nested layout, and use ensure_canvas_root before CanvasPanel positioning or sizing if the root is another panel. add_to_viewport requires PIE; start_pie_if_needed can request PIE and may require a retry.

游戏和系统工具命名空间

Tool Description Notes

manage_animation_physics Animation-and-physics tool namespace for physics Blueprint spawning, Blueprint physics settings, and Blueprint compilation actions.

manage_input Input tool namespace for creating classic UE4 input mappings. Focused on classic UE4 input-mapping authoring; use manage_editor.project_info for the canonical project summary.

manage_behavior_tree Behavior-tree tool namespace for creating, searching, and inspecting BehaviorTree assets. Focused on BehaviorTree asset discovery and inspection; use manage_editor.project_info for the canonical project summary.

manage_gas GAS tool namespace for searching gameplay-ability-related assets and inspecting their asset metadata.

排除的能力区域

这些功能区域有意不通过此UE4.27端口中的MCP表面暴露，因为它们在当前的Python环境中可靠地失败，并且只会增加提示或上下文开销，直到存在本机网桥。

许可证

根据 MIT许可证.