UnrealMCP — AI Bridge for Unreal Engine 5

UnrealMCP — 虚幻引擎 5 的 AI 桥梁

通过 Claude Code、Cursor、Windsurf 或任何 MCP 客户端控制虚幻引擎 5 编辑器。 只需提出需求，即可构建材质、连接 Blueprint 图表、创建 Niagara 系统、生成 Actor、编辑数据表并 分析性能。涵盖 15 个类别的 288 条命令，无需离开终端。

这是社区版

对其涵盖的功能而言，它稳定且功能完整。项目并未弃用，但也不再积极开发：新的子系统工作现在转向 CodeFizz Editor Agent， 这是持续维护的商业版本。此处的所有内容仍会正常运行，我们仍会查看问题，MIT 许可证也将永久有效。

如果你需要 Control Rig、PCG、Sequencer、Mutable、Procedural Vegetation、音频和 MetaSounds、 Behavior Trees 和 EQS，或适用于 UE 5.6 / 5.7 / 5.8 的打包二进制文件，请使用专业版。

社区版与专业版

查看完整命令列表 → · 文档 · 3 天免费试用

已经在使用 UE 5.8？ Epic 现已在 5.8 中提供第一方 MCP 服务（实验性，仅限 localhost）。 建议先试用，再决定是否购买。本仓库和专业版也都支持 5.6 和 5.7，而 Epic 的版本不支持这两个版本。

使用本仓库的两种方式

两者都通过编辑器内部的同一个 C++ 插件进行通信。可根据工作流选择其一，也可同时使用。

快速入门

选项 A：CLI（推荐用于 Claude Code）

# 1. Install
npm install -g unrealcli

# 2. Go to any UE5 project and install the plugin
cd YourProject/
ue-cli init

# 3. Open the editor, then verify
ue-cli health_check

就这么简单。无需 Python、配置文件或 MCP 设置。

选项 B：MCP 服务（适用于 Cursor、Windsurf 等）

# 1. Clone the plugin into your project
git clone https://github.com/aadeshrao123/Unreal-MCP.git Plugins/UnrealMCP

# 2. Install the Python MCP server
pip install unrealmcp

# 3. Add to your AI tool's config (see MCP Setup section below)

工作原理

                    ┌──────────────────────────────────────────┐
                    │         Unreal Engine 5 Editor            │
                    │                                          │
                    │   C++ Plugin (UnrealMCPBridge)           │
                    │   TCP server on localhost:55557           │
                    │   288 commands: materials, blueprints,   │
                    │   niagara, statetree, actors, data       │
                    │   tables, profiling, and more            │
                    └──────────────┬───────────────────────────┘
                                   │ TCP/JSON
                    ┌──────────────┴───────────────────────────┐
                    │                                          │
          ┌─────────┴─────────┐              ┌─────────┴──────────┐
          │   CLI (ue-cli)    │              │  MCP Server        │
          │   Go binary       │              │  Python (unrealmcp)│
          │   Direct TCP      │              │  stdio → TCP       │
          │                   │              │                    │
          │  Claude Code      │              │  Cursor, Windsurf, │
          │  (via Bash tool)  │              │  VS Code, Rider... │
          └───────────────────┘              └────────────────────┘

C++ 插件在编辑器内部运行，并通过 TCP 提供 288 条命令。CLI 和 MCP 服务是连接同一插件的两种不同入口。

CLI 参考

安装

# From npm (recommended)
npm install -g unrealcli

# Or download binary directly from GitHub Releases
# https://github.com/aadeshrao123/Unreal-MCP/releases

平台： Windows（x64）、macOS（Intel + Apple Silicon）、Linux（x64 + ARM64）

设置

# Navigate to your UE5 project
cd MyProject/

# Install the C++ plugin (one-time)
ue-cli init
# → Creates Plugins/UnrealMCP/ with C++ source
# → Patches .uproject to enable the plugin
# → Open editor to compile, then you're ready

# Verify everything works
ue-cli doctor

使用方法

# Every command follows this pattern:
ue-cli <command> [--flag value]

# Examples:
ue-cli health_check
ue-cli find_assets --class-type material --path /Game
ue-cli spawn_actor --name MyCube --type StaticMeshActor --location "[0,0,100]"
ue-cli get_data_table_rows --data-table-path /Game/Data/DT_Items
ue-cli save_all

# For complex params, use --json:
ue-cli build_material_graph --json '{"material_path":"/Game/M_Test","nodes":[...],"connections":[...]}'

# Or pipe from stdin:
echo '{"material_path":"/Game/M_Test","nodes":[...]}' | ue-cli build_material_graph --json -

帮助与发现

# See all commands grouped by category
ue-cli --help

# See flags for a specific command
ue-cli find_assets --help

# Dump all commands with descriptions, flags, and examples (for AI assistants)
ue-cli list_commands

全局标志

主要命令

资产

ue-cli find_assets --class-type material --path /Game/Materials
ue-cli list_assets --path /Game --class-filter blueprint
ue-cli get_asset_properties --asset-path /Game/Materials/M_Base
ue-cli import_asset --source-file "C:/Art/texture.png" --destination-path /Game/Textures
ue-cli save_asset --asset-path /Game/Materials/M_Base
ue-cli save_all

蓝图

ue-cli create_blueprint --name BP_MyActor --parent-class Actor
ue-cli add_component_to_blueprint --blueprint-path /Game/BP_MyActor --component-class StaticMeshComponent
ue-cli add_event_node --blueprint-name BP_MyActor --event-name BeginPlay
ue-cli compile_blueprint --blueprint-name BP_MyActor
ue-cli read_blueprint_content --blueprint-path /Game/BP_MyActor

材质

ue-cli create_material --name M_Red --path /Game/Materials
ue-cli build_material_graph --material-path /Game/Materials/M_Red \
  --nodes '[{"type":"Constant3Vector","pos_x":-400,"properties":{"Constant":"(R=1,G=0,B=0)"}}]' \
  --connections '[{"from_node":0,"to_node":"material","to_pin":"BaseColor"}]'
ue-cli create_material_instance --parent-path /Game/Materials/M_Base --name MI_Red

数据表

ue-cli get_data_table_schema --data-table-path /Game/Data/DT_Items
ue-cli get_data_table_rows --data-table-path /Game/Data/DT_Items
ue-cli add_data_table_row --data-table-path /Game/Data/DT_Items --row-name CopperOre \
  --data '{"DisplayName":"Copper Ore","StackSize":100}'
ue-cli update_data_table_row --data-table-path /Game/Data/DT_Items --row-name CopperOre \
  --data '{"StackSize":200}'

Actor 与关卡

ue-cli get_actors_in_level
ue-cli spawn_actor --name MyCube --type StaticMeshActor --location "[0,0,100]"
ue-cli spawn_blueprint_actor --blueprint-path /Game/BP_MyActor --location "[500,0,0]"
ue-cli find_actors_by_name --pattern "Light"
ue-cli get_world_info
ue-cli take_screenshot

性能分析

# Record → Stop → Analyze
ue-cli performance_start_trace --channels "cpu,gpu,frame"
# ... play the game ...
ue-cli performance_stop_trace
ue-cli performance_analyze_insight --query diagnose
ue-cli performance_analyze_insight --query flame --count 20
ue-cli performance_analyze_insight --query search --filter "ConveyorProcessor"

Enhanced Input

ue-cli create_input_action --asset-path /Game/Input/IA_Jump --value-type Boolean
ue-cli create_input_mapping_context --asset-path /Game/Input/IMC_Default
ue-cli add_key_mapping --context-path /Game/Input/IMC_Default --action-path /Game/Input/IA_Jump --key SpaceBar

Niagara VFX

# Create a system from an emitter template, then tweak it
ue-cli create_niagara_system --asset-path /Game/VFX/NS_Sparks \
  --template "/Niagara/DefaultAssets/FX_Sparks.FX_Sparks"
ue-cli get_niagara_system_info --asset-path /Game/VFX/NS_Sparks
ue-cli set_niagara_module_input --asset-path /Game/VFX/NS_Sparks \
  --emitter-name Sparks --stack SpawnStack \
  --module-name "Spawn Rate" --input-name SpawnRate --value 250
ue-cli compile_niagara_system --asset-path /Game/VFX/NS_Sparks

# Spawn it in the level
ue-cli spawn_niagara_effect --asset-path /Game/VFX/NS_Sparks --location "[0,0,200]"

StateTree

# Create a StateTree, add a state with a task, compile
ue-cli create_statetree --asset-path /Game/AI/ST_Enemy
ue-cli add_statetree_state --asset-path /Game/AI/ST_Enemy --state-name Patrol
ue-cli add_statetree_task --asset-path /Game/AI/ST_Enemy \
  --state-name Patrol --task-type "MassEnemyNestPatrolTask"
ue-cli add_statetree_transition --asset-path /Game/AI/ST_Enemy \
  --from-state Patrol --trigger OnEvent --event-tag "Enemy.SeePlayer"
ue-cli compile_statetree --asset-path /Game/AI/ST_Enemy

Mass 配置 Trait（精准编辑）

# Modify a single trait property without touching the rest of the trait array
ue-cli get_mass_config_traits --asset-path /Game/Mass/Enemy_Config
ue-cli set_mass_config_trait_property --asset-path /Game/Mass/Enemy_Config \
  --trait-class MassMovementTrait --property-name MaxSpeed --property-value 600

控件（UMG）

ue-cli get_widget_tree --widget-blueprint-path /Game/UI/WBP_HUD
ue-cli add_widget --widget-blueprint-path /Game/UI/WBP_HUD --widget-class TextBlock \
  --parent-widget-name RootCanvas --widget-name TitleText \
  --widget-properties '{"Text":"Hello World"}'

诊断

# Check entire setup
ue-cli doctor

# Output:
#   [ok] Project            MyProject/MyProject.uproject
#   [ok] Plugin directory   Plugins/UnrealMCP/ exists
#   [ok] Plugin source      Source/UnrealMCPBridge/ exists
#   [ok] UProject entry     UnrealMCP plugin listed and enabled
#   [ok] Port file          port 55557
#   [ok] TCP connection     Connected to 127.0.0.1:55557
#   [ok] Health check       Bridge is responsive
#   All checks passed. ue-cli is ready to use.

MCP 服务设置

适用于使用 Model Context Protocol 的 AI 工具（Cursor、Windsurf、VS Code 等）。

要求

• Unreal Engine 5.7（已在 5.7 上测试，可能也适用于更早的 5.x 版本）
• Python 3.10+
• UE5 插件（由 .uplugin 自动启用）：
  • PythonScriptPlugin
  • EditorScriptingUtilities
  • EnhancedInput

安装

pip install unrealmcp

设置脚本（手动配置的替代方案）

设置脚本会安装 unrealmcp pip 包，并自动为你的 AI 工具创建 MCP 配置。

Windows：

cd Plugins\UnrealMCP
install.bat

macOS / Linux：

cd Plugins/UnrealMCP
bash install.sh

脚本会询问要在哪里创建 MCP 配置：

配置你的 AI 工具

{
  "mcpServers": {
    "unreal": {
      "type": "stdio",
      "command": "unrealmcp"
    }
  }
}

{
  "mcpServers": {
    "unreal": {
      "command": "unrealmcp"
    }
  }
}

{
  "servers": {
    "unreal": {
      "command": "unrealmcp"
    }
  }
}

{
  "mcpServers": {
    "unreal": {
      "command": "unrealmcp"
    }
  }
}

{
  "mcpServers": {
    "unreal": {
      "command": "unrealmcp"
    }
  }
}

{
  "servers": [
    {
      "name": "unreal",
      "command": "unrealmcp"
    }
  ]
}

{
  "context_servers": {
    "unreal": {
      "source": "custom",
      "command": { "path": "unrealmcp" }
    }
  }
}

{
  "mcpServers": {
    "unreal": {
      "command": "unrealmcp"
    }
  }
}

全部 288 条命令

核心（2）

资源管理（16）

蓝图（22）

材质（35）

数据表（8）

数据资产 (12)

Actor 与关卡 (19)

Enhanced Input（21）

Widgets — UMG（11）

Niagara VFX（96）

端到端 Niagara 创作——读取完整堆栈，修改任意绑定（顶层或嵌套），从头创作草稿板动态输入，生成任意图表节点（包括数据接口成员函数），并查找编辑器下拉菜单公开的所有有效选项。基于 Niagara 导出的 ViewModel / Stack Graph API，并安全复刻未导出的辅助函数。

系统

发射器

模块（生成／更新／渲染堆栈）

堆栈输入绑定循环

参数与绑定

渲染器

草稿板 — CRUD 与应用

脚本属性（详情面板）

脚本参数（输入 / 输出）

图表内省

图表节点的增删改查

引脚管理

自定义 HLSL

事件和模拟阶段

关卡生成

发现（零猜测创作）

StateTree（33 个，新增）

读取和创作 StateTree 资源——状态、任务、评估器、转换、条件、参数和绑定。支持架构感知：兼容 StateTreeSchemaBase 和 Mass 架构变体。

读取

创作

修改

移除

发现

性能分析（3）

调试（2）

使用示例

这些示例适用于 CLI 和 MCP 服务。使用 CLI 时，AI 会通过 Bash 调用 ue-cli。使用 MCP 时，AI 会直接调用工具。

创建材质

Create a red metallic material at /Game/Materials/M_RedMetal
with roughness 0.3 and metallic 1.0

AI 会调用 create_material，然后调用 build_material_graph，将常量节点连接到 Base Color、Metallic 和 Roughness 引脚。

生成 Actor

Spawn 5 point lights in a circle around the origin at height 300

AI 会使用计算好的位置，调用 spawn_actor 五次，并设置 actor_type: "PointLight"。

创建蓝图

Create a Blueprint actor called BP_HealthPickup based on Actor,
add a Sphere Collision component and a Static Mesh component,
set it up so on BeginOverlap it prints "Health Picked Up"

AI 会使用 create_blueprint、add_component_to_blueprint、add_event_node、add_blueprint_node 和 connect_blueprint_nodes。

性能分析

Start a performance trace, play for 10 seconds, stop it,
then diagnose the bottlenecks

AI 会调用 performance_start_trace，等待，然后调用 performance_stop_trace，再调用 performance_analyze_insight 并设置 query: "diagnose"。

数据表管理

Show me the schema of DT_Items, then add a new row called
"IronIngot" with StackSize 100

AI 会调用 get_data_table_schema，然后使用适当的数据调用 add_data_table_row。

配置

自定义端口

添加到 Config/DefaultEngine.ini：

[UnrealMCP]
Port=55557

环境变量

# Force a specific port (overrides port file)
set UNREAL_MCP_PORT=55560

多个编辑器实例

每个编辑器都会自动选择唯一端口。CLI 和 MCP 服务会从 Saved/UnrealMCP/port.txt 读取端口。使用 --port 标志或 UNREAL_MCP_PORT 环境变量指定目标实例。

架构

插件结构

Plugins/UnrealMCP/
├── UnrealMCP.uplugin              # Plugin manifest
├── cli/                            # Go CLI source (ue-cli)
│   ├── cmd/                        # Command definitions (288 commands)
│   ├── internal/bridge/            # TCP client
│   ├── internal/project/           # Plugin embedding & project detection
│   └── npm/                        # npm package wrapper
├── unrealmcp/                      # Python MCP server
│   ├── _tcp_bridge.py              # TCP communication
│   └── tools/                      # Tool modules (one per category)
├── Source/UnrealMCPBridge/         # C++ editor plugin
│   ├── Public/                     # Headers
│   └── Private/                    # Implementation + command handlers
└── .github/workflows/release.yml   # CI: builds + GitHub Release + npm publish

通信协议

使用带长度前缀的 TCP 帧格式：

[4 bytes: big-endian payload length] [N bytes: UTF-8 JSON]

请求：{"type": "command_name", "params": {...}} 响应：{"status": "success", "result": {...}}

添加自定义命令

CLI 端（Go）

在相应的 cmd/*.go 文件中添加一个 CommandSpec：

{
    Name:    "my_command",
    Group:   "mygroup",
    Short:   "What it does",
    Long:    "Detailed description.",
    Example: "ue-cli my_command --param value",
    Params: []ParamSpec{
        {Name: "param", Type: "string", Required: true, Help: "Description"},
    },
},

MCP 端（Python）

在 unrealmcp/tools/ 中创建一个新文件：

# unrealmcp/tools/my_tools.py
from unrealmcp._bridge import mcp
from unrealmcp._tcp_bridge import _call

@mcp.tool()
def my_command(param: str) -> str:
    """Description shown to the AI assistant."""
    return _call("my_command", {"param": param})

在 unrealmcp/tools/__init__.py 中注册：

from unrealmcp.tools import my_tools  # noqa: F401

C++ 端

在 Source/UnrealMCPBridge/Private/Commands/ 中添加命令处理程序，并在 ExecuteCommand() 中注册。

支持的 AI 工具

故障排除

发布与分发

发布通过 GitHub Actions 自动完成。推送标签即可触发：

git tag v1.2.2 && git push origin v1.2.2
# → Builds 5 platform binaries
# → Creates GitHub Release
# → Publishes to npm + PyPI

贡献

• 遇到 Bug？ 提交问题
• 有功能建议？ 提交问题
• 想贡献代码？ Fork，进行修改，然后提交 PR

请参阅 CONTRIBUTING.md 了解贡献指南。

企业与工作室集成

需要将 Unreal MCP 集成到工作室的生产流程中？我会直接与游戏工作室合作，基于此工具构建定制的 AI 辅助工作流。

我可以提供：

• 流水线集成 — 将 Unreal MCP 接入现有的构建系统、CI/CD 和团队工作流，让每位美术和开发者都能开箱即用地通过 AI 助手操作 Unreal 项目
• 定制工具开发 — 构建符合工作室专有格式、内部工具和特定制作需求的 MCP 命令，弥补开源版本未覆盖的需求
• AI 工作流设计 — 设计并实现团队使用 AI 助手（Claude、Cursor、Copilot）配合 Unreal Engine 的方式，涵盖材质创建、关卡设计和资产流水线
• 高级材质与 Substrate 系统 — 程序化材质生成、Substrate 工作流、复杂着色器流水线，均可通过 MCP 全自动完成

联系方式：

• 电子邮件：[email protected]
• LinkedIn：linkedin.com/in/aadeshyadav
• Discord：destroyerpal
• 作品集：aadeshyadav.vercel.app

定制开发与支持

需要 Unreal 项目方面的帮助？我承接 UE5 C++ 全技术栈的合同项目，涵盖游戏玩法、多人游戏、编辑器工具和 Mass Entity 系统。详情请参阅 SUPPORT.md。

[email protected] · LinkedIn · 作品集 · Discord：destroyerpal

许可证

MPL-2.0 — 详情请参阅 LICENSE。