Unreal Editor

UE 5.3 编辑器插件 + Python MCP Server，通过本地 TCP JSON Lines 桥接，使 MCP 客户端（如 Claude / Codex）能操控 Unreal Engine 编辑器。

架构

MCP Client (Claude/Codex)
    ↕ stdio (JSON-RPC)
Python MCP Server (server.py)
    ↕ TCP/JSON Lines (127.0.0.1:9876)
UE Editor Plugin (UnrealEditorMCPBridge)
    ↕ UE API
Unreal Engine 5.3 Editor

传输层可替换，当前使用本地 TCP + 外部 Python Server，后续可评估 HTTP/SSE。

能力清单（96 Handler）

编辑器状态（7）

工具	说明
ue_ping	连通性测试
ue_get_bridge_runtime_status	传输层运行时状态（server_status / client_connected / last_error）
ue_get_editor_info	引擎版本、编辑器标识
ue_get_project_info	项目名称、磁盘路径
ue_get_world_state	世界名、Actor 数、World Partition 状态
ue_get_mcp_config	返回全部 action 注册表、模式、版本
ue_get_dirty_packages	列出所有未保存的脏包

资产浏览（6）

工具	说明
ue_list_assets	AssetRegistry 资产列表（路径/递归/类过滤）
ue_get_asset_info	单个资产详情
ue_list_blueprints	列出 Blueprint 资产
ue_list_materials	列出 Material/MaterialInstance
ue_list_widgets	列出 Widget Blueprint
ue_get_widget_info	Widget 树结构（root / parent / slot_class / is_variable）

Actor 操作（6）

工具	说明
ue_get_selected_actors	选中 Actor 列表（含 Transform）
ue_list_level_actors	关卡全部 Actor（含 Transform）
ue_level_get_actor_property	反射读取 Actor 属性
ue_level_get_component_property	反射读取组件属性
ue_spawn_actor	生成 Actor（类名+Transform）
ue_actor_delete	删除 Actor

编辑操作（5）

工具	说明
ue_level_set_actor_transform	设置 Actor 位置/旋转/缩放
ue_actor_set_property	反射写入 Actor 属性 + read-back
ue_component_set_property	反射写入组件属性 + read-back
ue_save_current_level	保存关卡
ue_viewport_screenshot	视口截图→PNG

资产编辑（11）

工具	说明
ue_create_blueprint	创建 Blueprint（指定父类/路径，含冲突检测）
ue_blueprint_add_variable	添加变量（bool/int/float/string/Vector/Rotator/Color）
ue_blueprint_add_function	添加函数图（含重名检测）
ue_blueprint_add_component	向 BP 的 SCS 添加组件（任意 UActorComponent 子类）
ue_create_widget_blueprint	创建 Widget Blueprint（可选 root_widget_class）
ue_widget_add_child	向 Widget 树添加控件（可选 index 插入位置）
ue_widget_remove_child	从 Widget 树移除控件
ue_widget_set_property	设置 Widget 属性 + read-back
ue_material_set_scalar_param	设置 MaterialInstance 标量参数
ue_material_set_vector_param	设置 MaterialInstance 向量/颜色参数
ue_material_set_texture_param	设置 MaterialInstance 纹理参数

Blueprint 图编辑（15）

工具	说明
ue_blueprint_create_actor_class	创建 Actor Blueprint 类
ue_blueprint_get_event_graph_info	获取 EventGraph 结构信息
ue_blueprint_add_event_node	添加/复用事件节点
ue_blueprint_add_call_function_node	添加 CallFunction 节点
ue_blueprint_add_node_by_class	通用 K2Node 工厂（Branch/Sequence/Comparison 等）
ue_blueprint_add_variable_node	创建变量 Get/Set 节点
ue_blueprint_set_pin_default	设置输入引脚默认值
ue_blueprint_get_function_signature	获取函数参数签名
ue_blueprint_connect_pins	连接引脚
ue_blueprint_disconnect_pins	断开引脚连接
ue_blueprint_remove_node	删除图节点
ue_blueprint_remove_variable	删除成员变量
ue_blueprint_compile_save	编译 Blueprint（可选保存）
ue_blueprint_apply_spec	从声明式 spec JSON 创建 BP 图（含 node_by_class / variable_get/set）
ue_blueprint_export_spec	导出已有 BP 的 EventGraph 为 spec

Enhanced Input（14）

工具	说明
ue_search_input_actions	搜索 InputAction 资产
ue_create_input_action	创建 InputAction（bool/float/vector2d/vector3d）
ue_get_input_action_info	获取 InputAction 详情（类型/路径）
ue_delete_input_action	删除 InputAction
ue_search_input_mapping_contexts	搜索 InputMappingContext 资产
ue_create_input_mapping_context	创建 InputMappingContext
ue_get_input_mapping_context_info	获取 IMC 详情 + 映射列表
ue_delete_input_mapping_context	删除 InputMappingContext
ue_add_input_mapping	向 IMC 添加键映射（InputAction+Key）
ue_remove_input_mapping	从 IMC 删除映射（按 index 或 key）
ue_set_input_mapping_action	修改现有映射的 InputAction
ue_set_input_mapping_key	修改现有映射的按键
ue_blueprint_add_enhanced_input_node	向 BP EventGraph 添加输入动作事件节点
ue_blueprint_add_imc_node	向 BP 添加映射上下文节点

Blueprint Utility（3）

工具	说明
ue_blueprint_search_functions	按关键字搜索 BlueprintCallable 函数
ue_blueprint_set_variable_default	设置 BP 变量 CDO 默认值
ue_blueprint_set_component_default	设置 BP 组件属性默认值

Blueprint CDO 属性（4）

工具	说明
ue_blueprint_get_cdo_property	读取蓝图 CDO 属性（标量/数组/结构体）
ue_blueprint_set_cdo_property	写入蓝图 CDO 属性
ue_blueprint_add_cdo_array	向 CDO TArray 追加元素（支持 field_overrides 修复 FProperty*/UObject* 指针）
ue_blueprint_remove_cdo_array	从 CDO 数组删除元素

GameplayTag（3）

工具	说明
ue_create_gameplay_tag	创建 GameplayTag（持久化到 DefaultGameplayTags.ini）
ue_list_gameplay_tags	列出已注册 GameplayTag
ue_search_gameplay_tags	按关键词搜索 GameplayTag

系统工具（1）

工具	说明
ue_close_modal_window	关闭 UE Editor 当前活跃的模态弹窗，避免阻塞 MCP 请求

PIE 运行时（5）

工具	说明
ue_pie_start	启动 Play In Editor 会话
ue_pie_stop	停止 PIE 会话
ue_pie_is_running	查询 PIE 是否运行中
ue_get_actor_state	获取 PIE 中 Actor 位置/旋转/速度
ue_set_level_default_pawn	设置关卡默认 Pawn 类

Widget 深化编辑（10）

工具	说明
ue_widget_get_property_schema	查询控件可编辑属性清单（name/type/editable）
ue_widget_get_slot_schema	查询控件 slot 类及可编辑属性
ue_widget_find	按 name/class 搜索 Widget 树节点
ue_widget_set_root	设定/替换 root widget（替换时丢弃已有子树）
ue_widget_reparent	移动节点到新 parent（含循环检测）
ue_widget_reorder_child	调整 sibling 顺序
ue_widget_rename	重命名节点（含冲突检测）
ue_widget_set_slot_property	设置 slot 布局属性（padding/alignment/anchors）
ue_widget_duplicate	复制节点/子树
ue_widget_wrap_with_panel	用容器面板包裹现有控件

事务控制（4）

工具	说明
ue_begin_transaction	开始事务（重入拒绝）
ue_end_transaction	结束事务（空拒绝）
ue_undo	撤销（自动结束活跃事务）
ue_redo	重做（自动结束活跃事务）

Python / 信息（3）

工具	说明
ue_execute_python_snippet	执行 UE Python 代码（Dangerous）
ue_get_blueprint_info	BP 详情：父类/变量/函数/接口
ue_get_material_info	材质详情：blend_mode/参数列表

MCP Resources（6）

Resource URI	类型	说明
ue://resources/overview	Static	项目架构、Handler 分类、单客户端模型
ue://resources/error-model	Static	UEBridgeError 分类、所有错误码、客户端指导
ue://resources/workflows	Static	常用调用链（BP 创建/编辑/Spec/Widget/事务/材质）
ue://resources/blueprint-spec	Static	11A/11B spec 格式、边界、round-trip、常见问题
ue://runtime/config	Live	当前 action registry / mode / token_enabled
ue://runtime/status	Live	当前 server_status / client_connected / last_error

目录

UnrealEditorMCP/                    ← Git 仓库根目录
├── UnrealEditorMCP.uproject
├── README.md
├── .gitignore
├── UnrealEditorMCP/              ← UE 项目根目录
│   ├── Config/
│   ├── Content/
│   ├── Source/
│   ├── Plugins/UnrealEditorMCPBridge/   # UE 编辑器插件
│   │   ├── Config/                      # ini 配置（Token/Port）
│   │   ├── Source/UnrealEditorMCPBridge/
│   │   │   ├── Public/                  # Handler 接口、调度器、Helpers
│   │   │   │   └── Handlers/            # 18 个领域文件（98 Handler）
│   │   │   └── Private/                 # 实现
│   │   └── Resources/
│   ├── Tools/MCPBridgeServer/           # Python MCP Server
│   │   ├── src/mcp_bridge_server/
│   │   │   ├── server.py                # MCP 入口
│   │   │   ├── bridge_client.py         # TCP 客户端
│   │   │   ├── resources.py             # MCP Resources 知识层（4 static + 2 live）
│   │   │   └── tool_schemas.py          # 98 tool schema 注册表
│   │   └── tests/
│   │       ├── test_stage12a.ps1          # 传输层稳态化验收
│   │       ├── test_stage14_resources.ps1 # 资源层验收（双模）
│   │       ├── test_resources_mcp.py      # MCP 协议层精确测试
│   │       ├── test_stage16_widget_deep.ps1 # Widget 深化验收
│   │       ├── test_stage17.ps1             # Blueprint Advanced 验收
│   │       └── test_stage18_playermove.ps1   # EI+PIE 端到端验收
│   └── .ai/                             # 项目治理（plan / log / dev）
└── Config/                              # 项目工程配置

运行前提

• UE 5.3（引擎路径通过 Epic Launcher 配置）
• Python 3.10+，安装依赖：pip install mcp
• 工程需启用插件：PythonScriptPlugin、EditorScriptingUtilities（.uproject 已配置）

启动

1. 启动 UE Editor

UnrealEditor.exe "UnrealEditorMCP.uproject"

插件加载后，确认日志输出：MCP Bridge listening on 127.0.0.1:9876

2. 启动 Python MCP Server

cd Tools/MCPBridgeServer
pip install -e .
python -m mcp_bridge_server

3. 注册到 MCP 客户端

在 Claude Desktop / Codex 的 MCP 配置中添加：

{
  "mcpServers": {
    "ue-bridge": {
      "command": "python",
      "args": ["-m", "mcp_bridge_server"],
      "cwd": "Tools/MCPBridgeServer"
    }
  }
}

配置

编辑 Plugins/UnrealEditorMCPBridge/Config/DefaultUnrealEditorMCPBridge.ini：

[UnrealEditorMCPBridge]
; 共享密钥，留空 = 开发模式（全部开放），填写 = 受限模式（Write/Dangerous 需 token）
Token=
; 监听端口
Port=9876

模式说明：

• 开发模式（Token 留空）：所有操作不受限制
• 受限模式（Token 非空）：Write 类操作需携带 _token 匹配；Python 端传 UEMCPServer(token="...") 自动注入

常见问题

现象	解决
端口被占用	关闭旧 Editor 进程或等待 2 分钟 TIME_WAIT 释放
UE Editor 未连接	确认插件编译并加载，检查日志 MCP Bridge listening
Python 执行失败 PYTHON_UNAVAILABLE	确认 .uproject 已启用 PythonScriptPlugin
请求超时返回 TIMEOUT (>5s)	UE Editor 可能被模态弹窗阻塞（如资产重名提示）。关闭弹窗后重试
创建资产 ASSET_CONFLICT	目标路径已有同名资产
双重 begin_transaction	先调用 end_transaction 再重新开始
断连后事务悬挂	插件自动结束活跃事务并丢弃残留请求

权限模型

Read (35)：ping / status / *_info / list_* / get_* / viewport_screenshot / dirty_packages / widget_*_schema / widget_find / search_*
Write (62)：spawn / set_* / delete / save / create_* / transaction / material_set_* / blueprint_* / widget_* / pie_* / input_* / cdo_* / close_modal_window
Dangerous (1)：execute_python_snippet

审计日志：所有 Write/Dangerous 操作自动输出 AUDIT: 日志。

当前限制

• 仅本地回环（127.0.0.1），不支持远程访问
• 单客户端独占 TCP 连接模式（第二连接被拒绝并返回 CLIENT_ALREADY_CONNECTED 错误）
• 运行时诊断：支持 ue_get_bridge_runtime_status + ue_get_mcp_config + ue://runtime/* Resources
• Blueprint：支持变量/函数添加 + 组件添加 + 节点级图编辑 + 声明式 spec 重建 + CDO 属性编辑
• Widget：完整 UMG Designer 闭环
• Enhanced Input：完整资产创建/按键映射/BP 事件节点
• GameplayTag：创建（持久化 ini）/搜索/列举
• 模态弹窗处理：支持 ue_close_modal_window 主动关闭阻断弹窗
• Python 协议桥：线程安全（UEBridgeClient.send 实例级 Lock 串行化）
• 不包含 Sequencer / Niagara / Animation 操作

License

MIT