UEMCP-虚幻引擎模型上下文协议

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

🚀 快速入门（2分钟）

# Clone and setup
git clone https://github.com/atomantic/UEMCP.git
cd UEMCP
./setup.sh

# Restart Claude Desktop or Claude Code and test:
# "List available UEMCP tools"
# "Organize the actors in the current map into a sensible folder structure and naming convention"

安装脚本会自动执行以下操作：

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

该脚本将检测您安装了哪些AI工具，并提供配置它们：

克劳德桌面和克劳德代码：原生MCP支持
亚马逊Q：通过MCP支持 ~/.aws/amazonq/agents/default.json
Google Gemini（命令行界面和代码辅助）：通过MCP支持 ~/.gemini/settings.json
OpenAI 代码专家：通过以下方式信任项目 ~/.codex/config.toml
GitHub Copilot：提供使用说明

📝 windows用户

推荐：使用WSL（Linux的Windows子系统）

# Install WSL if you haven't already
wsl --install

# In WSL/Ubuntu terminal:
git clone https://github.com/atomantic/UEMCP.git
cd UEMCP
./setup.sh

替代方案：Git Bash

安装 Git for Windows 其中包括Git Bash
跑 ./setup.sh 在Git Bash终端中

注：安装脚本会将插件复制（不是符号链接）到Windows上的UE项目，以避免权限问题。

高级选项：

# Specify UE project (automatically installs plugin via copy)
./setup.sh --project "/path/to/project.uproject"

# Install with symlink for UEMCP plugin development
./setup.sh --project "/path/to/project.uproject" --symlink

# Non-interactive mode (for CI/CD)
./setup.sh --project "/path/to/project.uproject" --no-interactive

提示示例

你可以要求代理做的事情是无限的。以下是按复杂性组织的示例提示：

基本命令

显示ModularOldTown文件夹中的所有墙网格
在位置1000500,0生成一个立方体
截取当前视口的屏幕截图
列出所有名字中有“门”的演员
将相机聚焦在玩家开始时
检查UE日志是否有任何错误

复杂任务

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

高级Python控件

使用python_proxy获取StaticMeshActor类型的所有参与者
执行Python将所有灯光更改为蓝色
运行Python代码分析该级别的材料使用情况
批量重命名所有参与者，以遵循一致的命名约定
创建用于程序级生成的自定义布局算法

🎯 主要功能：在编辑器模式下完全访问Python

这 python_proxy 该工具提供了对虚幻引擎的Python API的完整、不受限制的访问。 这意味着AI助手可以在UE编辑器中执行任何Python代码，从简单的查询到复杂的自动化脚本。所有其他MCP工具本质上都是围绕常见操作的便利包装，这些操作可以通过以下方式完成 python_proxy.

如果python_proxy可以做任何事情，为什么还要有其他工具？

效率：特定工具，如 actor_spawn 或 viewport_screenshot 是常见任务的优化快捷方式，消除了人工智能编写大量python代码的需要。
清晰度：命名工具使AI意图更清晰（例如，“生成一个参与者”与“执行Python代码”）
错误处理：专用工具提供更好的验证和错误消息
演出：与解析和执行任意Python进行简单操作相比，开销更小
可发现性：AI助手可以在不知道UE Python API的情况下轻松查看可用的操作

示例：截图

使用方便 viewport_screenshot mcp工具：

// One line, clear intent, automatic file handling
viewport_screenshot({ width: 1920, height: 1080, quality: 80 })

使用 python_proxy 对于同一任务：

# Much more complex, requires knowing UE Python API
import unreal
import os
import time

# Get project paths
project_path = unreal.Paths.project_saved_dir()
screenshot_dir = os.path.join(project_path, "Screenshots", "MacEditor")

# Ensure directory exists
if not os.path.exists(screenshot_dir):
    os.makedirs(screenshot_dir)

# Generate filename with timestamp
timestamp = int(time.time() * 1000)
filename = f"uemcp_screenshot_{timestamp}.png"
filepath = os.path.join(screenshot_dir, filename)

# Take screenshot with proper settings
unreal.AutomationLibrary.take_high_res_screenshot(
    1920, 1080,
    filepath,
    camera=None,
    capture_hdr=False,
    comparison_tolerance=unreal.ComparisonTolerance.LOW
)

# Would need additional error handling, JPEG conversion for quality, etc.
result = f"Screenshot saved to: {filepath}"

这样想： python_proxy 是功能强大的命令行，而其他工具是方便的GUI按钮。

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

🛠 可用工具

UEMCP提供 36个MCP工具 涵盖7个类别，提供全面的虚幻引擎控制：

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

项目信息 -获取当前UE项目信息
资产列表 -列出项目资产并进行筛选
资产信息 -获取详细的资产信息（边界、插座、材料）

🎭 演员管理（8个工具）

actor_spawn -在级别中生成演员
actor_重复 -使用偏移复制现有参与者
actor_delete -按名称删除演员
actor_modify -修改演员属性（位置、旋转、比例、网格）
actor_organize -将演员组织到World Outliner文件夹中
actor_snap_to_scocket -将演员扣到插座位置，实现模块化建筑
批次_典当 -在一次操作中高效地生成多个参与者
地点_验证 -验证模块化组件的放置（间隙、重叠）

🏗️ 水平操作（3个工具）

level_actors -列出具有属性的级别中的所有参与者
level_save -保存当前级别
水平排水管 -获取世界大纲视图文件夹结构

📹 视口控制（8个工具）

viewport_screenshot -捕获视口图像
viewport_camera -设置相机位置和旋转
viewport_mode -切换到标准视图（俯视图、前视图、侧视图、透视图）
viewport_focus -将相机聚焦在特定演员身上
viewport_render_mode -更改渲染模式（灯光、线框等）
viewport_bounds -获取当前视口边界
viewport_fit -自动在视口中调整演员
viewport_look_at -将相机指向特定坐标/演员

🎨 材料系统（4个工具）

材料清单 -列出具有过滤功能的项目材料
材料信息 -获取详细的材料信息和参数
material_create -创建新材质或材质实例
材料_应用 -将材质应用于演员网格组件

🔷 蓝图系统（5个工具）

蓝图_创建 -创建新的蓝图类
蓝图列表 -列出带有元数据的项目蓝图
blueprint_info -获取蓝图结构（组件、变量、函数）
蓝图堆 -编制蓝图并报告错误
蓝图_文档 -生成全面的蓝图文档

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

python_proxy ⭐ - 使用完全的UE API访问权限执行任意Python代码
test_连接 -测试Python侦听器连接和状态
restart_listener -重新启动Python侦听器（热重新加载）
ue_logs -获取最近的虚幻引擎日志条目
帮助 📚 - 获取全面的帮助和工具文档

🔧 MCP服务器层工具（Node.js处理的其他工具）

撤销 -撤消上次操作
重做 -恢复以前撤消的操作
历史列表 -显示带有时间戳的操作历史记录
检查点创建 -创建命名保存点
checkpoint_restore -恢复到指定的检查点
批处理操作 -在单个请求中执行多个操作

🔍 验证功能

所有演员操作工具(actor_spawn, actor_modify, actor_delete, actor_duplicate)现在支持自动验证，以确保操作按预期成功：

验证参数（默认值： true)-验证是否在虚幻引擎中正确应用了更改
检查位置、旋转、比例、网格和文件夹值是否与请求的值匹配
返回验证结果，包括任何错误或警告
集 validate: false “鲁莽模式”跳过性能验证

验证示例：

// Spawn with automatic validation
actor_spawn({ 
  assetPath: "/Game/Meshes/Wall", 
  location: [1000, 0, 0],
  rotation: [0, 0, 90]
})
// Response includes: validated: true/false, validation_errors: [...]

// Modify without validation for faster execution
actor_modify({ 
  actorName: "Wall_01", 
  location: [2000, 0, 0],
  validate: false  // Skip validation check
})

🚀 批量操作

这 batch_operations 该工具允许您在单个HTTP请求中执行多个操作，将批量操作的开销减少80-90%：

// Execute multiple operations efficiently
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"
    }
  ]
})
// Returns: success/failure status for each operation with timing info

优点：

速度提高80-90% 比单个工具需要批量操作
原子执行 -在一个请求中处理的所有操作
详细结果 -每个操作的单独成功/失败状态
性能跟踪 -执行时间和内存管理

______________________________________________________________________

总计：36个MCP工具 跨7个类别，通过模型上下文协议接口提供全面的虚幻引擎自动化和控制。

🚀 v2.0.0动态架构所有工具定义现在都是从Python动态加载的，消除了代码重复，并确保Python是工具功能的唯一真实来源。这些工具的范围从基本的项目查询到高级的蓝图操作，包括 python_proxy 该工具为专用工具未涵盖的任何操作提供对虚幻引擎完整的Python API的无限访问。

💡 帮助入门

这 help 该工具具有自我记录功能！ 从这里开始：

// First command to run - shows all tools and workflows
help({})

// Learn about specific tools
help({ tool: "actor_spawn" })
help({ tool: "python_proxy" })

// Explore by category
help({ category: "level" })     // All level editing tools
help({ category: "viewport" })  // Camera and rendering tools

蓝图开发工作流程

// 1. List existing Blueprints in your project
blueprint_list({ path: "/Game/Blueprints" })

// 2. Create a new interactive door Blueprint
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. Analyze Blueprint structure 
blueprint_info({ blueprintPath: "/Game/Blueprints/BP_InteractiveDoor" })

// 4. Compile and check for errors
blueprint_compile({ blueprintPath: "/Game/Blueprints/BP_InteractiveDoor" })

// 5. Generate documentation
blueprint_document({ 
  blueprintPath: "/Game/Blueprints/BP_InteractiveDoor",
  outputPath: "/Game/Documentation/BP_InteractiveDoor.md"
})

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

# With python_proxy, you can do anything you could do in UE's Python console:
import unreal

# Batch operations
actors = unreal.get_editor_subsystem(unreal.EditorActorSubsystem).get_all_level_actors()
for actor in actors:
    if "Old" in actor.get_actor_label():
        actor.destroy_actor()

# Complex asset queries
materials = unreal.EditorAssetLibrary.list_assets("/Game/Materials", recursive=True)
for mat_path in materials:
    material = unreal.EditorAssetLibrary.load_asset(mat_path)
    # Analyze or modify material properties...

# Editor automation
def auto_layout_actors(spacing=500):
    selected = unreal.get_editor_subsystem(unreal.EditorActorSubsystem).get_selected_level_actors()
    for i, actor in enumerate(selected):
        actor.set_actor_location(unreal.Vector(i * spacing, 0, 0))

📋 先决条件

Node.js 20+和npm
虚幻引擎5.1+（建议5.4+）
Python 3.11（与UE的内置版本匹配）
MCP兼容的AI客户端（Claude Desktop、Claude Code、Gemini、Codex、Q）

💡 用法示例

重要提示：使用Claude代码的工作流

当使用UEMCP和Claude Code时，正确的工作流程是：

首先启动虚幻引擎 打开项目
然后启动Claude Code -它将自动启动MCP服务器并连接
如果重新启动虚幻引擎，MCP服务器将自动重新连接

- 服务器每5秒运行一次运行状况检查，以便快速重新连接 - 它将检测UE何时脱机，并在几秒钟内恢复联机 - 您将在Claude Code日志中看到连接状态

备注：MCP服务器（理论上）对UE重启具有弹性——重启虚幻引擎时不需要重启Claude Code。一旦UE再次运行，连接将自动恢复。

🏗 建筑

AI → Local MCP Server (Node.js) →  Cloud Unreal Engine (Python Listener)

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

UEMCP使用 两层结构 这将MCP协议处理与虚幻引擎集成分开。这使我们能够独立于与它们交互的客户端部署虚幻的引擎编辑器，无论是在本地还是在云中。

🔄 开发工作流程

# Local development - both tiers on same machine
AI Client ←→ MCP Server (localhost:8080) ←→ UE Python (localhost:8765)

# Remote UE development - UE on cloud/server
AI Client ←→ MCP Server (localhost:8080) ←→ UE Python (remote-server:8765)

# Team development - shared UE instance  
AI Client A ←→ MCP Server A ←→ Shared UE (team-server:8765)
AI Client B ←→ MCP Server B ←→ Shared UE (team-server:8765)

模块化Python架构

Python插件使用一个干净的模块化架构（从一个2090行的文件重构而来）：

操作模块：演员、视口、资源、关卡和系统操作的重点模块
命令注册表：自动命令发现和调度
验证框架：可选的术后验证，基于容差的比较
一致的错误处理：在所有业务中实现标准化
代码减少85%：使用专用MCP工具与python_proxy时

📖 请参阅详细的架构文档→

🧑‍💻 发展

插件开发

推荐：使用符号链接进行热重新加载

init脚本现在支持自动创建符号链接：

# Install with symlink (recommended for development)
node init.js --project "/path/to/project.uproject" --symlink

# Or let it ask you interactively (defaults to symlink)
node init.js --project "/path/to/project.uproject"

符号链接的好处：

✅ 直接在git存储库中编辑插件文件
✅ 变化反映在 restart_listener()
✅ 无需来回复制文件
✅ 版本控制友好

# Available helpers in UE Python console:
status()            # Check if running
stop_listener()     # Stop listener
start_listener()    # Start listener

热重新加载代码更改

您可以重新加载虚幻插件，并从mcp或虚幻引擎python命令提示符重新启动python服务器：

restart_listener()

添加新工具

在中添加命令处理程序 plugin/Content/Python/uemcp_listener.py
在中创建MCP工具包装器 server/src/tools/
在中注册工具 server/src/index.ts

测试

# Run full test suite (mimics CI)
./test-ci-locally.sh

# Individual tests
npm test              # JavaScript tests
python -m pytest      # Python tests
npm run lint          # Linting

诊断测试

使用诊断测试脚本验证您的MCP设置：

# Quick diagnostic checklist
node scripts/mcp-diagnostic.js

# Interactive test suite (requires user verification)
node scripts/diagnostic-test.js

诊断测试验证所有MCP功能，包括：

连接和项目信息
资产管理（列表、信息）
级别操作（生成、修改、删除参与者）
视口控制（相机、屏幕截图、渲染模式）
材料系统（列出、创建、应用）
高级功能（python_proxy、批处理操作）

预期成功率：100% 对于正确配置的系统。

📚 文档

安装参考 -手动设置和配置详细信息
建筑 -系统设计和组件
故障排除 -常见问题和解决方案
例子 -高级使用模式和实验
MCP与Python -代码减少85%比较
Python解决方法 -已知的UE Python限制
贡献 -如何做出贡献
发展 -面向AI助手和开发人员

⚠️ 已知限制

当前MCP工具限制

蓝图图形编辑：无法以编程方式编辑蓝图节点图（可视化脚本逻辑），但可以创建、分析、编译和记录蓝图
动画蓝图：没有直接的动画状态机或混合树操作
电平流：无动态水平装载/卸载控制

Python API问题

演员参考: get_actor_reference() 不适用于显示名称（已实施解决方法）
视口方法：几个已弃用（参见 Python API解决方案)

可用的解决方案

大多数剩余的限制都可以通过使用 python_proxy 工具。请参阅我们的文档：

Python API解决方案 -常见修复
房屋建筑实验 -现实世界的解决方案

🗺️ 路线图

看计划.md 了解详细的路线图和发布标准。

🤝 贡献

分叉存储库
创建要素分支
虚幻引擎测试
提交拉取请求

📄 许可证

MIT许可证-请参阅许可证文件

UEMCP (Atomantic)

快速接入

详细介绍