Unreal MCP (Sallah Boussettah)

UnrealMCP

虚幻引擎最全面的MCP服务器。 87工具, 45种蓝图节点类型, 16个类别 --通过AI控制整个虚幻编辑器。

一个混合的Python+C++系统，允许AI助手（Claude、Cursor、Windsurf）创建蓝图、操纵节点图、管理参与者、编辑材料、构建UI小部件、设置动画状态机、调试带有断点的蓝图、填充数据表、配置增强输入——所有这些都可以通过自然语言通过 模型上下文协议.

专为虚幻引擎5.6+打造。

为什么是不现实的CP？

建筑

AI Client ──stdio──> Python MCP Server ──TCP:55555──> C++ UE5 Editor Plugin
                     (87 tools)                       (82 command handlers)
                     mcp-server/                      plugin/UnrealMCP/

• Python MCP服务器 --通过stdio实现MCP协议。将工具调用转换为TCP命令。
• C++UE5插件 --在虚幻编辑器中运行。监听TCP端口55555，使用本机UE5 C++API在游戏线程上执行命令。
• 协议 --4字节大端序长度前缀+JSON有效载荷。基于UUID的请求/响应匹配。支持高达10MB的有效载荷（用于截图）。

在端口55557上与Epic的内置MCP一起运行，两者独立运行，没有冲突。

快速设置

1.安装Python MCP服务器

cd mcp-server
python -m venv .venv
.venv/Scripts/activate   # Windows
pip install -e .

2.安装UE5插件

复制 plugin/UnrealMCP/ 进入UE5项目 Plugins/ 文件夹并编译。通过检查输出日志进行验证：

UnrealMCP: Listening on port 55555

3.配置您的AI客户端

添加到您的 .claude.json （或使用 claude mcp add):

{
  "mcpServers": {
    "UnrealMCP": {
      "command": "
/mcp-server/.venv/Scripts/python.exe",
      "args": ["-m", "unreal_mcp.server"],
      "cwd": "
/mcp-server"
    }
  }
}

你能用它做什么？

• 人工智能辅助游戏原型 --用自然语言描述游戏机制，让人工智能创建具有正确节点和连接的蓝图
• 自动化蓝图构建 --以编程方式构建复杂的节点图（健康系统、库存、人工智能行为）并自动布局它们
• 关卡设计 --创建/加载/保存地图，管理流媒体子级别，生成角色，设置变换，分配材质
• 运行时测试 --在编辑器会话中启动播放、暂停/恢复游戏、读取日志、在运行时使用断点调试蓝图
• UI原型设计 --使用17种小部件类型创建小部件蓝图，设置属性，构建完整的UMG层次结构
• 动画设置 --创建动画蓝图、状态机、过渡、混合空间和蒙太奇
• 数据驱动设计 --为物品、统计数据、对话、战利品创建和填充数据表；从CSV导入
• 输入配置 --创建InputActions和InputMappingContexts，使用修饰符和触发器配置WASD/游戏手柄绑定
• 批量操作 --生成数十个参与者，添加许多节点，或在单个工具调用中连接整个图形

工具参考

蓝图工具（11）

节点图工具（9）

45 Supported Node Types (click to expand)

示例：

PrintString     → node_type="CallFunction", function_name="PrintString", target_class="KismetSystemLibrary"
Delay           → node_type="CallFunction", function_name="Delay", target_class="KismetSystemLibrary"
Branch          → node_type="Branch"
For Loop        → node_type="MacroInstance", params={"macro_name": "ForLoop"}
Cast To Actor   → node_type="DynamicCast", params={"target_class": "Character"}
Make Vector     → node_type="MakeStruct", params={"struct_type": "Vector"}
Spawn Actor     → node_type="SpawnActorFromClass"
Timeline        → node_type="Timeline", params={"timeline_name": "DoorTimeline"}
Input Action    → node_type="EnhancedInputAction", params={"input_action_path": "/Game/Input/IA_Jump"}

演员工具（6）

属性工具（5）

材料工具（4）

水平工具（7）

资产工具（5）

视口工具（2）

控制台工具（3）

PIE工具（4）

批处理工具（3）

小工具（5）

动画工具（7）

调试工具（5）

DataTable工具（6）

增强型输入工具（5）

技术细节

使用UE5 C++API

• 蓝图: FKismetEditorUtilities::CreateBlueprint(), FBlueprintEditorUtils::AddMemberVariable(), CompileBlueprint()
• 节点图: UK2Node_CallFunction, UK2Node_Event, UK2Node_IfThenElse, UEdGraphSchema_K2::TryCreateConnection()
• 属性: FProperty::ImportText_Direct() / ExportTextItem_Direct(), PreEditChange() / PostEditChangeProperty()
• 材料: UMaterialFactoryNew::FactoryCreateNew(), UMaterial::GetEditorOnlyData(), UMaterialEditingLibrary
• 等级: UEditorLoadingAndSavingUtils, UEditorLevelUtils, FEditorFileUtils
• 资产: UAutomatedAssetImportData, ImportAssetsAutomated(), IAssetRegistry::GetAssets()
• 馅饼: GEditor->RequestPlaySession(), RequestEndPlayMap(), SetPIEWorldsPaused()
• 数据表: UDataTableFactory, FDataTableEditorUtils::AddRow(), CreateTableFromCSVString()
• 增强输入: UInputAction, UInputMappingContext::MapKey()，修饰符和触发器
• 截图：Win32 PrintWindow(), IImageWrapper PNG编码
• 线程安全：所有命令通过以下方式在游戏线程上执行 AsyncTask(ENamedThreads::GameThread)，通过以下方式撤消支持 FScopedTransaction

项目结构

UnrealMCP/
  mcp-server/                  # Python MCP server
    src/unreal_mcp/
      server.py                # Entry point, FastMCP setup
      connection.py            # TCP client (4-byte prefix protocol)
      tools/                   # Tool definitions by category
        blueprint.py           #  11 Blueprint tools
        node_graph.py          #   9 Node Graph tools
        actor.py               #   6 Actor tools
        property.py            #   5 Property tools
        material.py            #   4 Material tools
        viewport.py            #   2 Viewport tools
        console.py             #   3 Console tools
        level.py               #   7 Level tools
        asset.py               #   5 Asset tools
        pie.py                 #   4 PIE tools
        batch.py               #   3 Batch tools
        widget.py              #   5 Widget tools
        anim.py                #   7 Animation tools
        debug.py               #   5 Debug tools
        datatable.py           #   6 DataTable tools
        input.py               #   5 Input tools
  plugin/UnrealMCP/            # C++ UE5 editor plugin
    Source/UnrealMCP/
      Private/
        MCPTCPServer.cpp       # TCP listener, command dispatch
        Commands/              # 82 command handlers by category
      Public/
        Commands/              # Header files

需求

• 虚幻引擎5.6+
• Python 3.10+
• MCP SDK 1.0+(pip install mcp)
• Windows（主要；macOS/Linux未测试）
• Visual Studio 2022（用于插件编译）
• MCP兼容的AI客户端（克劳德代码、克劳德桌面、光标、Windsurf等）

贡献

欢迎捐款。看 进展.md 关于路线图和已知问题。

许可证

麻省理工学院