py-ue5-mcp-server

py-ue5-mcp-server

面向 Claude 的 Unreal Engine 5 MCP 服务

此代码仓库包含一个 Model Context Protocol (MCP) Python 服务，可让 Claude 通过自然语言与 Unreal Engine 5 交互。借助 Remote Control API，此集成让你能够直接通过与 Claude 对话，在 Unreal Engine 中创建、操作和控制 3D 对象与 Blueprint Actor。

概述

此 MCP 服务在 Claude 的自然语言处理能力与 Unreal Engine 强大的 3D 环境之间架起了桥梁。用户只需描述自己想在 Unreal Engine 中创建或修改的内容，Claude 就会解读这些请求，并通过 MCP 服务执行相应操作。

主要功能

• 自然语言控制：通过与 Claude 的对话文本创建和操作 3D 对象
• Blueprint Actor 交互：通过简单的文本提示词访问 Blueprint Actor 中的函数
• 场景管理：通过文本指令构建、修改和布置场景
• 资产发现：通过 Claude 搜索并使用 Unreal 项目中的资产
• 实时反馈：在 Unreal Engine 视口中即时查看效果

要求

• Python 3.10+
• Unreal Engine 5.x，且已启用 Remote Control API 插件
• 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. 确保已启用 Remote Control 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 之间建立双向通信通道。主要组件包括：

# Create the MCP server with lifespan support
mcp = FastMCP(
    "Unreal-Engine-MCP",
    description="Unreal Engine integration through the Model Context Protocol (Default unit: CENTIMETERS)",
    lifespan=server_lifespan
)

2. 连接到 Unreal Engine

服务通过 Remote Control API 连接到 Unreal Engine。Remote Control API 是运行在 Unreal 内部的内置 HTTP 服务：

# Default Unreal Engine Remote Control API settings
UE_HOST = "http://127.0.0.1"  # localhost
UE_PORT = "30010"             # default port
UE_URL = f"{UE_HOST}:{UE_PORT}/remote/object/call"

3. 核心工具

服务通过函数装饰器向 Claude 提供多个工具：

@mcp.tool()
async def get_all_scene_actors(ctx: Context) -> str:
    """Get a list of all actors in the current level"""
    # Implementation...

@mcp.tool()
async def spawn_actor(ctx: Context, blueprint_path: str, ...) -> str:
    """Spawn a blueprint actor in the current Unreal Engine level"""
    # Implementation...
    
@mcp.tool()
async def spawn_snowman_family(ctx: Context, ...) -> str:
    """Spawns a family of three snowmen in the current Unreal Engine level"""
    # Implementation...
    
@mcp.tool()
async def modify_actor(ctx: Context, actor_path: str, ...) -> str:
    """Modify an existing actor's properties in the Unreal Engine level"""
    # Implementation...

4. Actor 操作

服务可以通过 Remote Control API 调用，在场景中创建和修改 Actor：

# Illustrative example of how actor creation works
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 Remote Control API，并以 JSON 格式返回结果。

特色功能

1. 创建雪人家庭

一项展示功能是通过一条命令创建一个雪人家庭。服务将：

• 创建一个初始雪人 Actor
• 复制它，创建另外两个位置、旋转和缩放各不相同的雪人
• 将它们排列成家庭队形

这展示了如何通过简单的自然语言命令创建复杂场景。

2. 复制蓝图 Actor

服务可以使用 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]:
    """Calls the Duplicate function in a Blueprint actor"""
    # Implementation...

3. 修改 Actor

服务支持修改已有 Actor 的任意属性：

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

故障排除

连接问题

• 启动 Claude Desktop 前，确保 Unreal Engine 正在运行
• 检查 Unreal Engine 中是否已启用 Remote Control API 插件
• 确认防火墙未阻止通过端口 30010（默认端口）进行通信
• 查看 Claude Desktop 控制台中的错误消息

命令执行问题

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

服务日志

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

2023-11-15 14:32:45,123 - Unreal-MCP-Server - INFO - Unreal Engine MCP server starting up...
2023-11-15 14:32:45,125 - Unreal-MCP-Server - INFO - Default unit system: CENTIMETERS (1 Unreal Unit = 1 cm)
2023-11-15 14:32:45,234 - Unreal-MCP-Server - INFO - Connected to Unreal Engine Remote Control API

开发与自定义

添加新功能

向服务添加新功能：

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

示例：

@mcp.tool()
async def your_new_function(ctx: Context, param1: str, param2: int) -> str:
    """
    Description of what your function does
    
    Parameters:
        param1: Description of param1
        param2: Description of param2
        
    Returns:
        JSON string with the result
    """
    # Implementation...

自定义蓝图交互

你可以修改现有函数，或为自己的 Actor 创建专用函数，让服务适配自定义蓝图 Actor。

致谢

本项目受到类似的 Claude MCP 集成项目启发，尤其是 runeape-sats 编写的原始 Unreal Engine MCP 服务。特别感谢 Anthropic 团队打造 Claude，并实现此类集成。