AI导哈

虚幻引擎AI控制插件

UnrealMCP是一个为虚幻引擎设计的插件，允许AI助手通过TCP连接以JSON-RPC 2.0协议程序化控制编辑器，支持100+原生命令。

  • by DeVoe09
  • C++
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 DeVoe09/UnrealMCP

使用说明

UnrealMCP

虚幻引擎的模型上下文协议（MCP）服务器插件 它允许AI助手以编程方式控制编辑器。通过TCP公开100多个具有JSON-RPC 2.0支持的本地命令——演员、蓝图、材料、UMG小部件、AI行为树等。

将其放入您的项目中 Plugins/ 文件夹，启用它，并连接任何兼容MCP的客户端（Claude Code、自定义脚本等），开始使用AI进行构建。

特性

  • 100+本地命令 涵盖演员、蓝图、材料、UMG、AI、资产、视口等
  • MCP协议支持 使用JSON-RPC 2.0(initialize, tools/list, tools/call)用于标准MCP客户端兼容性
  • 传统协议 向后兼容简单 {"type":"command","params":{...}} JSON格式
  • 多客户端支持 每个连接和MPSC命令队列都有专用线程
  • 游戏线程执行 确保所有UE API调用安全地发生在正确的线程上
  • 工具栏状态小部件 带实时连接指示灯（红色/琥珀色/绿色，带脉冲动画）
  • Python集成 通过 execute_python 适用于本机命令未涵盖的任何内容
  • 速率限制 每个客户端都有可配置的令牌桶
  • 完整的产权制度 具有点路径导航、类型感知JSON转换、Map/Set/Array支持

安装

来源（插件文件夹）

  1. 将此存储库克隆或下载到项目的 Plugins/ 目录：
YourProject/
  Plugins/
    UnrealMCP/
      Source/
      UnrealMCP.uplugin
      ...
  1. 重新生成项目文件（右键单击 .uproject >“生成Visual Studio项目文件”）。
  2. 构建并启动虚幻编辑器。
  3. 插件在端口上自动启动TCP服务器 55557.寻找 主控程序 工具栏中的指示器。

验证安装

连接任何TCP客户端并发送：

{"id":"1","type":"ping","params":{}}

您应该收到：

{"id":"1","success":true,"result":{"status":"pong","version":"2.0.1","engine":"5.7.0","port":55557}}

快速开始

传统协议（简单JSON）

{"id":"1","type":"spawn_actor","params":{"class":"StaticMeshActor","label":"MyCube","location":{"x":0,"y":0,"z":100}}}

MCP协议（JSON-RPC 2.0）

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-05","clientInfo":{"name":"my-client","version":"1.0"}}}

{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"spawn_actor","arguments":{"class":"PointLight","label":"MyLight","location":{"x":100,"y":0,"z":200}}}}

建筑

┌──────────────────────────────────────────────────────────────┐
│  MCP Client (Claude Code, Python script, etc.)               │
│  Sends: {"jsonrpc":"2.0","method":"tools/call",...}          │
└───────────────────────┬──────────────────────────────────────┘
                        │ TCP port 55557
                        ▼
┌──────────────────────────────────────────────────────────────┐
│  FMCPTCPServer                                               │
│                                                              │
│  ┌────────────────────────────────────────────────────────┐  │
│  │ Accept Thread (FRunnable::Run)                         │  │
│  │ • Listens for incoming TCP connections                 │  │
│  │ • Spawns per-client FClientConnectionRunnable          │  │
│  └────────────────────────────────────────────────────────┘  │
│                        │                                     │
│  ┌────────────────────────────────────────────────────────┐  │
│  │ Per-Client Threads                                     │  │
│  │ • Reads newline-delimited JSON from socket             │  │
│  │ • Parses command (legacy or JSON-RPC 2.0)              │  │
│  │ • Enqueues to MPSC command queue                       │  │
│  │ • Waits on completion event (configurable timeout)     │  │
│  └────────────────────────────────────────────────────────┘  │
│                        │                                     │
│  ┌────────────────────────────────────────────────────────┐  │
│  │ Game Thread (FTickableEditorObject::Tick)               │  │
│  │ • Dequeues commands (up to MaxCommandsPerTick)         │  │
│  │ • Dispatches to Cmd_* handler                          │  │
│  │ • Signals completion event → unblocks client thread    │  │
│  └────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────┘

命令参考

所有命令接受 actor_path 或 actor_label 用于演员分辨率，可选 use_pie / world_context_index 世界选择。

核心

命令 关键参数 描述
ping —— 连通性检查；返回版本和引擎信息
get_status -- 已连接的客户端、端口、运行状态
execute_python code 在编辑器中运行Python（需要PythonScriptPlugin）
execute_python_file file_path 运行Python脚本文件
console_command command 执行UE控制台命令
get_project_info -- 项目名称、路径、引擎版本

MCP协议

命令 描述
initialize JSON-RPC 2.0握手；返回服务器信息和功能
tools/list 返回所有用于LLM发现的带有inputSchema的工具定义
tools/call 统一工具调用： {"name":"<tool>","arguments":{...}}

水平与世界

命令 关键参数 描述
open_level level_path 加载一个级别
get_world_contexts -- 列出世界背景
get_current_level -- 当前级别信息
get_loaded_levels -- 所有加载+流媒体级别
load_streaming_level level_path 添加流媒体级别
unload_streaming_level level_path 删除流媒体级别

演员

命令 关键参数 描述
get_all_actors class_filter, label_filter 列出具有可选筛选器的参与者
spawn_actor class, label, location, rotation 小丑演员
delete_actor actor参数 删除一个actor
delete_actors class_name, tags 按筛选器批量删除
duplicate_actor 演员参数 克隆演员
get_actor_transform actor参数 获取位置/旋转/比例
set_actor_transform 演员+变换 设置变换
get_actor_bounds actor参数 获取来源和范围
get_actor_property 男演员 property 按点路径读取属性
set_actor_property 男演员 property, value 设置属性（JSON）
get_all_properties 演员或 object_path 列出所有属性
get_actor_components actor参数 列出组件
place_actor_from_asset asset_path 从内容资产中放置
set_component_property 男演员 component, property, value 设置组件属性
get_component_property 男演员 component, property 获取组件属性

大纲视图和文件夹

命令 关键参数 描述
set_actor_folder 男演员 folder_path 将演员移动到文件夹
set_selected_actors_folder folder_path 将所选内容移动到文件夹
list_actor_folders -- 列出所有文件夹
create_actor_folder folder_path 创建文件夹

资源和内容浏览器

命令 关键参数 描述
get_assets path, class_filter 列出资产
get_selected_assets -- 内容浏览器选择
set_selected_assets asset_paths 设置CB选择
create_asset asset_name, package_path, asset_class 创建资产
create_blueprint blueprint_name, package_path, parent_class 创建蓝图
create_material asset_path 创建材质
save_asset / save_level / save_all -- 保存操作
delete_asset / duplicate_asset / rename_asset asset_path 资产管理
get_asset_full_metadata asset_path 完整元数据+标签
get_unsaved_assets -- 列出不良资产
get_content_subpaths base_path 文件夹层次结构
create_content_folder folder_path 创建内容文件夹

蓝图图

命令 关键参数 描述
get_blueprint_graphs blueprint_name 列出图表
create_blueprint_graph blueprint_name, graph_name, graph_type 创建函数/宏图
find_blueprint_nodes blueprint_name 查找节点
get_node_info blueprint_name, node_id 节点详细信息
add_blueprint_event_node blueprint_name, event_name 添加事件
add_blueprint_function_node blueprint_name, function_name 添加函数调用
add_blueprint_branch_node blueprint_name 添加分支
add_blueprint_sequence_node blueprint_name 添加序列
add_blueprint_switch_node blueprint_name 添加开关（int）
add_blueprint_switch_string_node blueprint_name 添加开关（字符串）
add_blueprint_switch_enum_node blueprint_name, enum_path 添加开关（枚举）
add_blueprint_timeline_node blueprint_name 添加时间线
add_blueprint_foreach_node blueprint_name 添加每个
add_blueprint_gate_node blueprint_name 添加门
add_blueprint_multigate_node blueprint_name 添加MultiGate
connect_blueprint_nodes source_node_id, source_pin, target_node_id, target_pin 连接引脚
disconnect_blueprint_pins 与连接相同 断开链接
set_node_position node_id, x, y 移动节点
set_pin_default_value node_id, pin_name, value 设置引脚默认值
delete_blueprint_node node_id 删除节点
compile_blueprint blueprint_name 编译

蓝图变量

命令 关键参数 描述
get_blueprint_variables blueprint_name 列出变量
add_blueprint_variable blueprint_name, variable_name, variable_type 添加变量
set_blueprint_variable_default blueprint_name, variable_name, value 设置默认值
add_blueprint_variable_node blueprint_name, variable_name，get/set 添加get/set节点

材料

命令 关键参数 描述
get_material_expressions material_path 列出表达式
add_material_expression material_path, expression_class 添加表达式
delete_material_expression material_path 删除表达式
connect_material_expressions material_path, from, to 连接表达式
connect_material_property material_path, from, property 连接到属性
get_material_expression_pins material_path 获取密码信息
recompile_material material_path 推荐

UMG（小部件蓝图）

命令 关键参数 描述
create_widget_blueprint asset_name, package_path 创建小部件BP
add_umg_widget widget_blueprint_path, widget_class 添加小部件
remove_umg_widget widget_blueprint_path, widget_name 删除小部件
get_umg_tree widget_blueprint_path 小部件层次结构
set_umg_slot_content widget_blueprint_path, slot_name 设置命名插槽

AI（行为树、黑板、感知）

命令 关键参数 描述
create_behavior_tree asset_name, package_path 创建BT+黑板对
add_blackboard_key blackboard_path, key_name, key_type 添加黑板键
run_behavior_tree 控制器+ behavior_tree_path 在AI控制器上运行BT
configure_ai_perception 控制器参数 添加/配置视觉
configure_ai_hearing 控制器参数 添加/配置听觉
add_bt_composite_node behavior_tree_path, composite_type 添加选择器/序列
add_bt_decorator_node behavior_tree_path 添加装饰器
add_bt_service_node behavior_tree_path 添加服务
rebuild_navigation -- 重建NavMesh

视口和选择

命令 关键参数 描述
get_selected_actors -- 列出所选演员
set_selected_actors actor_paths 设置选择
focus_viewport actor_label 或坐标 移动相机
get_viewport_transform -- 相机位置/旋转/FOV
set_viewport_fov fov 设置视场
take_screenshot filename 请求截图
list_viewports -- 枚举视口

配置

添加到您的项目 DefaultEngine.ini:

[UnrealMCP]
Port=55557
CommandTimeoutSeconds=30
MaxCommandsPerTick=16
MaxRequestLineBytes=16777216
RateLimitEnabled=0
设置 默认值 说明
Port 55557 TCP侦听端口
CommandTimeoutSeconds 30 等待游戏线程执行的最长时间
MaxCommandsPerTick 16 每个编辑器刻度处理的最大命令数
MaxRequestLineBytes 16 MB 最大单个请求大小
RateLimitEnabled 0 启用每个客户端令牌桶速率限制

项目结构

UnrealMCP/
├── Source/UnrealMCP/
│   ├── Public/
│   │   ├── MCPTCPServer.h          # Server class, command queue, protocol
│   │   ├── MCPStatusWidget.h       # Toolbar indicator widget
│   │   └── UnrealMCPModule.h       # Module interface
│   ├── Private/
│   │   ├── MCPTCPServer.cpp        # Server + all 100+ command handlers
│   │   ├── MCPStatusWidget.cpp     # Widget implementation
│   │   └── UnrealMCPModule.cpp     # Module startup, config, toolbar
│   └── UnrealMCP.Build.cs          # Build rules and dependencies
├── Scripts/
│   ├── test_ai_commands.py         # Python test suite
│   └── README.md                   # Test documentation
├── docs/
│   └── AI_COMMANDS_IMPLEMENTATION_PLAN.md
├── UnrealMCP.uplugin               # Plugin manifest
├── LICENSE                          # MIT License
├── CONTRIBUTING.md                  # Contribution guidelines
├── CHANGELOG.md                     # Version history
├── SECURITY.md                      # Security policy
└── README.md                        # This file

需求

  • 虚幻引擎 5.7+（仅限编辑器版本）
  • 平台：Windows（Win64）
  • 可选的：Python脚本插件（用于 execute_python 命令）

安全

此插件在您的计算机上打开一个TCP服务器以供开发使用。看 安全.md 有关网络暴露和负责任披露的详细信息。

贡献

欢迎投稿！看 贡献.md 有关报告错误、提交PR、代码样式和添加新命令的指南。

许可证

该项目根据 MIT许可证.

另见

相关 MCP