技术文档摘要

UEMCP - Unreal Engine Model Context Protocol

UEMCP通过两层架构将AI助手与Unreal Engine连接起来，该架构将MCP服务器（Node.js）与Python编辑器插件分离，从而实现Unreal Engine编辑器的远程部署。此实现提供了对常见UE Python API操作的优化封装，减少了高达85%的代码生成。仓库包括AI客户端的自动设置、全面的开发环境以及三个专门的Claude代理以增强UE工作流程。与包管理的MCP服务器不同，此仓库设计为可克隆并可能分叉，以实现最大程度的定制和开发灵活性。

<img src="https://github.com/atomantic/UEMCP/releases/download/v1.0.0/uemcp-demo.gif" alt="UEMCP Demo" width="100%">

🚀 快速开始（2分钟）

# 克隆并设置
git clone https://github.com/atomantic/UEMCP.git
cd UEMCP
./setup.sh

# 重启Claude Desktop或Claude Code并测试：
# "列出可用的UEMCP工具"
# "将当前地图中的角色组织成合理的文件夹结构和命名约定"

设置脚本会自动：

• ✅ 检查并安装所需的Node.js（通过Homebrew、apt、yum或nvm）
• ✅ 安装依赖项并构建服务器
• ✅ 检测并配置AI开发工具（Claude Desktop、Claude Code、Amazon Q、Gemini Code Assist、OpenAI Codex）
• ✅ 设置您的Unreal Engine项目路径
• ✅ 可选地将UEMCP插件安装到您的项目中

脚本会检测您已安装的AI工具，并提供配置选项：

• Claude Desktop & Claude Code：原生MCP支持
• Amazon Q：通过~/.aws/amazonq/agents/default.json支持MCP
• Google Gemini（CLI & Code Assist）：通过~/.gemini/settings.json支持MCP
• OpenAI Codex：通过~/.codex/config.toml支持可信项目
• GitHub Copilot：提供使用说明

📝 Windows用户

推荐：使用WSL（Windows Subsystem for Linux）

# 如果尚未安装，请安装WSL
wsl --install

# 在WSL/Ubuntu终端中：
git clone https://github.com/atomantic/UEMCP.git
cd UEMCP
./setup.sh

替代方案：Git Bash

• 安装适用于Windows的Git，其中包含Git Bash
• 在Git Bash终端中运行./setup.sh

注意：设置脚本会在Windows上将插件复制（而不是符号链接）到您的UE项目中，以避免权限问题。

高级选项：

# 指定UE项目（自动通过复制安装插件）
./setup.sh --project "/path/to/project.uproject"

# 使用符号链接安装UEMCP插件进行开发
./setup.sh --project "/path/to/project.uproject" --symlink

# 非交互模式（用于CI/CD）
./setup.sh --project "/path/to/project.uproject" --no-interactive

提示示例

您可以要求代理执行的任务是无限的。这里有一些按复杂度组织的提示示例：

基本命令

• 显示ModularOldTown文件夹中的所有墙网格
• 在位置1000, 500, 0处生成一个立方体
• 截取当前视口的屏幕截图
• 列出名称中带有'Door'的所有角色
• 将相机聚焦在起始点
• 检查UE日志中的任何错误

复杂任务

• 将Rive Unreal插件添加到此项目：https://github.com/rive-app/rive-unreal
• 使用此项目的OldModularTown资产来建造房屋的第一层
• 查找所有迷宫墙壁并在X轴上翻转它们以翻转迷宫
• 向HorseArena地板添加纹理和颜色材质

高级Python控制

• 使用python_proxy获取所有类型为StaticMeshActor的角色
• 执行Python代码将所有灯光变为蓝色
• 运行Python代码分析关卡中的材质使用情况
• 批量重命名所有角色以遵循一致的命名约定
• 创建自定义布局算法以进行程序化关卡生成

🎯 关键特性：编辑模式下的完全Python访问

**python_proxy工具提供了对Unreal Engine Python API的完全无限制访问。**这意味着AI助手可以在UE编辑器内执行任何Python代码——从简单的查询到复杂的自动化脚本。其他所有MCP工具本质上都是围绕可以通过python_proxy完成的常见操作的便利包装器。

为什么有其他工具如果python_proxy可以做一切？

1. 效率：特定工具如actor_spawn或viewport_screenshot是常见任务的优化快捷方式，消除了AI编写大量Python代码的需求。
2. 清晰性：命名工具使AI意图更明确（例如，“生成一个角色”与“执行Python代码”）。
3. 错误处理：专用工具提供更好的验证和错误消息。
4. 性能：对于简单操作，比解析和执行任意Python代码的开销小。
5. 可发现性：AI助手可以轻松查看可用的操作，而无需了解UE Python API。

示例：截取屏幕截图

使用方便的viewport_screenshot mcp工具：

// 一行代码，意图明确，自动文件处理
viewport_screenshot({ width: 1920, height: 1080, quality: 80 })

使用python_proxy完成相同任务：

# 更加复杂，需要了解UE Python API
import unreal
import os
import time

# 获取项目路径
project_path = unreal.Paths.project_saved_dir()
screenshot_dir = os.path.join(project_path, "Screenshots", "MacEditor")

# 确保目录存在
if not os.path.exists(screenshot_dir):
    os.makedirs(screenshot_dir)

# 生成带时间戳的文件名
timestamp = int(time.time() * 1000)
filename = f"uemcp_screenshot_{timestamp}.png"
filepath = os.path.join(screenshot_dir, filename)

# 使用适当设置截取屏幕截图
unreal.AutomationLibrary.take_high_res_screenshot(
    1920, 1080,
    filepath,
    camera=None,
    capture_hdr=False,
    comparison_tolerance=unreal.ComparisonTolerance.LOW
)

# 需要额外的错误处理、JPEG转换等
result = f"屏幕截图保存至：{filepath}"

可以这样理解：python_proxy是强大的命令行，而其他工具则是方便的GUI按钮。

📊 详细比较MCP工具与python_proxy →（平均减少80%以上的代码！）

🛠 可用工具

UEMCP提供了7类共36个MCP工具，以实现全面的Unreal Engine控制：

📦 项目及资产管理（3个工具）

• project_info - 获取当前UE项目信息
• asset_list - 列出项目资产并过滤
• asset_info - 获取详细的资产信息（边界、套接字、材质）

🎭 角色管理（8个工具）

• actor_spawn - 在关卡中生成角色
• actor_duplicate - 偏移复制现有角色
• actor_delete - 根据名称删除角色
• actor_modify - 修改角色属性（位置、旋转、缩放、网格）
• actor_organize - 将角色组织到World Outliner文件夹中
• actor_snap_to_socket - 将角色固定到套接字位置以进行模块化建筑
• batch_spawn - 高效地一次操作生成多个角色
• placement_validate - 验证模块化组件放置（间隙、重叠）

🏗️ 关卡操作（3个工具）

• level_actors - 列出关卡中所有角色及其属性
• level_save - 保存当前关卡
• level_outliner - 获取World Outliner文件夹结构

📹 视口控制（8个工具）

• viewport_screenshot - 捕获视口图像
• viewport_camera - 设置相机位置和旋转
• viewport_mode - 切换标准视图（顶部、正面、侧面、透视）
• viewport_focus - 将相机聚焦于特定角色
• viewport_render_mode - 更改渲染模式（光照、线框等）
• viewport_bounds - 获取当前视口边界
• viewport_fit - 自动调整视口中的角色
• viewport_look_at - 将相机指向特定坐标/角色

🎨 材质系统（4个工具）

• material_list - 列出项目材质并过滤
• material_info - 获取详细的材质信息和参数
• material_create - 创建新的材质或材质实例
• material_apply - 将材质应用于角色网格组件

🔷 蓝图系统（5个工具）

• blueprint_create - 创建新的蓝图类
• blueprint_list - 列出项目蓝图及其元数据
• blueprint_info - 获取蓝图结构（组件、变量、函数）
• blueprint_compile - 编译蓝图并报告错误
• blueprint_document - 生成全面的蓝图文档

⚙️ 系统及高级（5个工具）

• python_proxy ⭐ - 执行任意Python代码，具有完整的UE API访问权限
• test_connection - 测试Python监听器连接状态
• restart_listener - 重启Python监听器（热重载）
• ue_logs - 获取最近的Unreal Engine日志条目
• help 📚 - 获取全面的帮助和工具文档

🔧 MCP服务器层工具（由Node.js处理的附加工具）

• undo - 撤销上次操作
• redo - 重新执行之前撤销的操作
• history_list - 显示带有时间戳的操作历史
• checkpoint_create - 创建命名保存点
• checkpoint_restore - 恢复到命名检查点
• batch_operations - 在单个请求中执行多个操作

🔍 验证功能

所有角色操作工具（actor_spawn、actor_modify、actor_delete、actor_duplicate）现在支持自动验证，以确保操作按预期成功：

• validate 参数（默认：true） - 验证更改是否正确应用于Unreal Engine
• 检查位置、旋转、缩放、网格和文件夹值是否与请求值匹配
• 返回验证结果，包括任何错误或警告
• 设置validate: false进入“鲁莽模式”，跳过验证以提高性能

带有验证的示例：

// 带有自动验证的生成
actor_spawn({ 
  assetPath: "/Game/Meshes/Wall", 
  location: [1000, 0, 0],
  rotation: [0, 0, 90]
})
// 响应包括：validated: true/false, validation_errors: [...]

// 不带验证的修改以加快执行速度
actor_modify({ 
  actorName: "Wall_01", 
  location: [2000, 0, 0],
  validate: false  // 跳过验证检查
})

🚀 批量操作

batch_operations工具允许您在一个HTTP请求中高效地执行多个操作，批量操作的开销减少了80-90%：

// 高效地执行多个操作
batch_operations({
  operations: [
    {
      operation: "actor_spawn",
      params: { assetPath: "/Game/Meshes/Wall", location: [0, 0, 0] },
      id: "wall_1"
    },
    {
      operation: "actor_spawn", 
      params: { assetPath: "/Game/Meshes/Wall", location: [300, 0, 0] },
      id: "wall_2"
    },
    {
      operation: "viewport_camera",
      params: { location: [150, -500, 300], rotation: [0, -30, 0] },
      id: "camera_pos"
    },
    {
      operation: "viewport_screenshot",
      params: { width: 800, height: 600 },
      id: "screenshot"
    }
  ]
})
// 返回每个操作的成功/失败状态及计时信息

优点：

• 80-90%更快：批量操作比单独调用工具快
• 原子执行：所有操作在一个请求中处理
• 详细结果：每个操作的个别成功/失败状态
• 性能跟踪：执行时间和内存管理

---

总计：36个MCP工具，分布在7个类别中，通过模型上下文协议接口提供全面的Unreal Engine自动化和控制。

🚀 v2.0.0动态架构：所有工具定义现在都从Python动态加载，消除了代码重复，并确保Python是工具能力的唯一真实来源。这些工具范围从基本的项目查询到高级的蓝图操作，python_proxy工具提供了对Unreal Engine完整Python API的无限访问，以执行未被专用工具覆盖的操作。

💡 开始使用帮助

help工具是自我文档化的！ 从这里开始：

// 第一个要运行的命令 - 显示所有工具和工作流
help({})

// 学习特定工具
help({ tool: "actor_spawn" })
help({ tool: "python_proxy" })

// 按类别探索
help({ category: "level" })     // 所有关卡编辑工具
help({ category: "viewport" })  // 相机和渲染工具

蓝图开发工作流

// 1. 列出项目中的现有蓝图
blueprint_list({ path: "/Game/Blueprints" })

// 2. 创建一个新的互动门蓝图
blueprint_create({
  className: "BP_InteractiveDoor",
  parentClass: "Actor",
  components: [
    { name: "DoorMesh", type: "StaticMeshComponent" },
    { name: "ProximityTrigger", type: "BoxComponent" }
  ],
  variables: [
    { name: "IsOpen", type: "bool", defaultValue: false },
    { name: "OpenRotation", type: "rotator", defaultValue: [0, 0, 90] }
  ]
})

// 3. 分析蓝图结构 
blueprint_info({ blueprintPath: "/Game/Blueprints/BP_InteractiveDoor" })

// 4. 编译并检查错误
blueprint_compile({ blueprintPath: "/Game/Blueprints/BP_InteractiveDoor" })

// 5. 生成文档
blueprint_document({ 
  blueprintPath: "/Game/Blueprints/BP_InteractiveDoor",
  outputPath: "/Game/Documentation/BP_InteractiveDoor.md"
})

示例：使用python_proxy进行复杂操作

# 使用python_proxy，您可以执行在UE的Python控制台中能做的任何事情：
import unreal

# 批量操作
actors = unreal.EditorLevelLibrary.get_all_level_actors()
for actor in actors:
    if "Old" in actor.get_actor_label():
        actor.destroy_actor()

# 复杂的资产查询
materials = unreal.EditorAssetLibrary.list_assets("/Game/Materials", recursive=True)
for mat_path in materials:
    material = unreal.EditorAssetLibrary.load_asset(mat_path)
    # 分析或修改材质属性...

# 编辑器自动化
def auto_layout_actors(spacing=500):
    selected = unreal.EditorLevelLibrary.get_selected_level_actors()
    for i, actor in enumerate(selected):
        actor.set_actor_location(unreal.Vector(i * spacing, 0, 0))

📋 先决条件

• Node.js 18+ 和 npm
• Unreal Engine 5.1+（推荐5.4+）
• Python 3.11（与UE内置版本匹配）
• 与MCP兼容的AI客户端（Claude Desktop、Claude Code、Gemini、Codex、Q）

💡 使用示例

重要：与Claude Code的工作流程

当使用UEMCP与Claude Code时，正确的流程是：

1. 首先启动Unreal Engine，打开您的项目
2. 然后启动Claude Code - 它将自动启动MCP服务器并连接
3. 如果您重启Unreal Engine，MCP服务器将自动重新连接
   • 服务器每5秒进行健康检查以快速重新连接
   • 它将在几秒钟内检测到UE离线并重新上线
   • 您将在Claude Code的日志中看到连接状态

注意：理论上，MCP服务器对UE重启具有弹性——重启Unreal Engine时不需要重启Claude Code。一旦UE再次运行，连接将自动恢复。

🏗 架构

AI → 本地MCP服务器（Node.js）→ 云端Unreal Engine（Python监听器）

为什么拆分Node.js MCP服务器 + Python UE桥接？

UEMCP使用两层架构，将MCP协议处理与Unreal Engine集成分离。这使得我们可以独立于与其交互的客户端部署Unreal Engine编辑器，无论是本地还是在云端。

🔄 开发工作流

# 本地开发 - 两个层级在同一台机器上
AI客户端 ←→ MCP服务器（localhost:8080）←→ UE Python（localhost:8765）

# 远程UE开发 - UE在云端/服务器上
AI客户端 ←→ MCP服务器（localhost:8080）←→ UE Python（远程服务器:8765）