py-ue5-mcp-server

用于 Claude 的 Unreal Engine 5 MCP 服务器

此仓库包含一个模型上下文协议 (MCP) Python 服务器，该服务器使 Claude 能够通过自然语言与 Unreal Engine 5 交互。通过利用远程控制 API，此集成允许您直接通过与 Claude 的对话在 Unreal Engine 中创建、操作和控制 3D 对象和蓝图 Actor。

概述

此 MCP 服务器弥合了 Claude 的自然语言处理能力与 Unreal Engine 强大的 3D 环境之间的差距。用户只需描述他们想要在 Unreal Engine 中创建或修改的内容，Claude 将解释这些请求并通过 MCP 服务器执行相应的操作。

主要特性

• 自然语言控制：使用与 Claude 的对话文本创建和操作 3D 对象
• 蓝图 Actor 交互：通过简单的文本提示访问蓝图 Actor 中的函数
• 场景管理：使用基于文本的指令构建、修改和排列场景
• 资产发现：通过 Claude 搜索和利用 Unreal 项目中的资产
• 实时反馈：在 Unreal Engine 视口中获得即时视觉结果

要求

• Python 3.10+
• 启用远程控制 API 插件的 Unreal Engine 5.x
• Claude Desktop (Windows)
• Unreal Engine 基础知识

安装

1. 设置仓库

git clone https://github.com/yourusername/ue5-mcp.git
cd ue5-mcp
pip install uv mcp requests

2. 配置 Claude Desktop

1. 打开 Claude Desktop
2. 转到 File → Settings → Developer → Edit Config
3. 将以下内容添加到 claude_desktop_config.json，调整路径到您的本地仓库：

{
  "mcpServers": {
    "ue5-mcp": {
      "command": "uv",
      "args": ["--directory", "C:\\path\\to\\ue5-mcp", "run", "ue5_mcp_server.py"],
      "env": {}
    }
  }
}

注意: 如果您配置了其他 MCP 服务器，您可能需要禁用它们以防止冲突。

3. 准备 Unreal Engine

1. 打开 Unreal Engine 和您的项目
2. 确保已启用远程控制 API 插件：
   • Edit → Plugins → 搜索 "Remote Control API"
   • 检查是否已启用，如果需要，重新启动编辑器

用法

入门

1. 启动 Unreal Engine 和您的项目
2. 启动 Claude Desktop（如果已运行，请重新启动）
3. 开始与 Claude 聊天，讨论在 Unreal Engine 中创建或修改内容

示例提示

以下是一些您可以与 Claude 一起使用的示例提示：

• "在位置 0, 100, 50 创建一个雪人"
• "在场景中生成一个雪人家庭"
• "修改中心雪人的比例使其更大"
• "将雪人移动到位置 100, 200, 0"
• "将雪人旋转 45 度"
• "获取场景中所有 Actor 的列表"

理解单位

服务器使用厘米作为所有测量的默认单位：

• 1 Unreal 单位 = 1 厘米
• 一个标准雪人的尺寸约为 350cm × 350cm (3.5m × 3.5m)
• 定位和缩放都相对于这个基于厘米的系统

工作原理

技术实现

UE5-MCP 服务器使用以下核心组件：

1. MCP 服务器框架

该服务器使用 FastMCP 构建，它在 Claude 和 Unreal Engine 之间建立双向通信通道。主要组件是：

# 创建具有生命周期支持的 MCP 服务器
mcp = FastMCP(
    "Unreal-Engine-MCP",
    description="通过模型上下文协议进行 Unreal Engine 集成（默认单位：厘米）",
    lifespan=server_lifespan
)

2. 连接到 Unreal Engine

服务器通过远程控制 API 连接到 Unreal Engine，这是一个内置的 HTTP 服务器，在 Unreal 内部运行：

# 默认 Unreal Engine 远程控制 API 设置
UE_HOST = "http://127.0.0.1"  # localhost
UE_PORT = "30010"             # 默认端口
UE_URL = f"{UE_HOST}:{UE_PORT}/remote/object/call"

3. 核心工具

服务器通过函数装饰器向 Claude 公开几个工具：

@mcp.tool()
async def get_all_scene_actors(ctx: Context) -> str:
    """获取当前关卡中所有 Actor 的列表"""
    # 实现...

@mcp.tool()
async def spawn_actor(ctx: Context, blueprint_path: str, ...) -> str:
    """在当前的 Unreal Engine 关卡中生成一个蓝图 Actor"""
    # 实现...
    
@mcp.tool()
async def spawn_snowman_family(ctx: Context, ...) -> str:
    """在当前的 Unreal Engine 关卡中生成一个由三个雪人组成的家庭"""
    # 实现...
    
@mcp.tool()
async def modify_actor(ctx: Context, actor_path: str, ...) -> str:
    """修改 Unreal Engine 关卡中现有 Actor 的属性"""
    # 实现...

4. Actor 操作

服务器可以通过远程控制 API 调用在场景中创建和修改 Actor：

# Actor 创建工作原理的说明性示例
spawn_payload = {
    "objectPath": "/Script/EditorScriptingUtilities.Default__EditorLevelLibrary",
    "functionName": "SpawnActorFromClass",
    "parameters": {
        "ActorClass": blueprint_path,
        "Location": {"X": location[0], "Y": location[1], "Z": location[2]},
        "Rotation": {"Pitch": rotation[0], "Yaw": rotation[1], "Roll": rotation[2]}
    },
    "generateTransaction": True
}

每个操作都作为 HTTP 请求执行到 Unreal Engine 远程控制 API，该 API 以 JSON 格式返回结果。

特色功能

1. 雪人家庭创建

其中一个展示功能是能够使用单个命令创建一个雪人家庭。服务器将：

• 创建一个初始雪人 Actor
• 复制它以创建另外两个具有不同位置、旋转和比例的雪人
• 将它们排列成家庭队形

这演示了如何使用简单的自然语言命令创建复杂的场景。

2. 蓝图 Actor 复制

服务器可以使用其原生蓝图函数复制场景中现有的 Actor：

async def duplicate_snowman(
    snowman_actor_path: str, 
    location: Tuple[float, float, float], 
    rotation: Tuple[float, float, float], 
    scale: Tuple[float, float, float], 
    name: Optional[str]
) -> Optional[str]:
    """调用蓝图 Actor 中的 Duplicate 函数"""
    # 实现...

3. Actor 修改

服务器支持修改现有 Actor 的任何属性：

• 更改位置、旋转和比例
• 重命名 Actor
• 仅更新特定属性，同时保留其他属性

故障排除

连接问题

• 确保在启动 Claude Desktop 之前 Unreal Engine 正在运行
• 检查远程控制 API 插件是否已在 Unreal Engine 中启用
• 验证防火墙是否阻止端口 30010（默认端口）上的通信
• 在 Claude Desktop 控制台中查找错误消息

命令执行问题

• 从简单的命令开始以验证基本功能
• 检查请求的语法
• 在 Unreal Engine 输出日志中查找错误消息
• 确保引用的 Actor 或资产存在于您的项目中

服务器日志

服务器生成详细的日志，可以帮助诊断问题：

2023-11-15 14:32:45,123 - Unreal-MCP-Server - INFO - Unreal Engine MCP 服务器正在启动...
2023-11-15 14:32:45,125 - Unreal-MCP-Server - INFO - 默认单位系统：厘米（1 Unreal 单位 = 1 厘米）
2023-11-15 14:32:45,234 - Unreal-MCP-Server - INFO - 已连接到 Unreal Engine 远程控制 API

开发和自定义

添加新功能

要向服务器添加新功能：

1. 创建一个新的辅助函数来实现所需的行为
2. 使用 @mcp.tool() 装饰器将其公开给 Claude
3. 使用文档字符串清楚地记录该函数

示例：

@mcp.tool()
async def your_new_function(ctx: Context, param1: str, param2: int) -> str:
    """
    描述您的函数的作用
    
    参数：
        param1：param1 的描述
        param2：param2 的描述
        
    返回：
        带有结果的 JSON 字符串
    """
    # 实现...

自定义蓝图交互

您可以通过修改现有函数或创建特定于您的 Actor 的新函数来调整服务器以与您的自定义蓝图 Actor 一起使用。

致谢

该项目受到了 Claude 类似 MCP 集成的启发，特别是 runeape-sats 的原始 Unreal Engine MCP 服务器。特别感谢 Anthropic 团队创建 Claude 并实现这些类型的集成。