py-ue5-mcp-server

Unreal Engine 5 MCP 服务器用于 Claude

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

概述

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

主要特性

• 自然语言控制：使用与 Claude 的对话文本创建和操作 3D 对象
• 蓝图演员交互：通过简单的文本提示访问蓝图演员中的函数
• 场景管理：使用基于文本的指令构建、修改和排列场景
• 资产发现：通过 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. 转到 文件 → 设置 → 开发者 → 编辑配置
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 插件：
   • 编辑 → 插件 → 搜索“远程控制 API”
   • 确认它已启用，并根据需要重启编辑器

使用

开始使用

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

示例提示

这里有一些您可以与 Claude 使用的示例提示：

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

理解单位

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

• 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"  # 本地主机
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:
    """获取当前级别中所有演员的列表"""
    # 实现...

@mcp.tool()
async def spawn_actor(ctx: Context, blueprint_path: str, ...) -> str:
    """在当前 Unreal Engine 级别中生成蓝图演员"""
    # 实现...
    
@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 级别中现有演员的属性"""
    # 实现...

4. 演员操作

服务器可以通过远程控制 API 调用来创建和修改场景中的演员：

# 演示如何创建演员的工作方式
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
}

每个动作都是作为对 Unreal Engine 远程控制 API 的 HTTP 请求执行的，返回结果为 JSON 格式。

特色能力

1. 雪人家庭创建

展示功能之一是能够通过单一命令创建一个雪人家庭。服务器将：

• 创建初始雪人演员
• 复制它以创建两个更多不同位置、旋转和比例的雪人
• 将它们排列成家庭形式

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

2. 蓝图演员复制

服务器可以使用其原生蓝图函数复制场景中存在的演员：

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]:
    """调用蓝图演员中的复制函数"""
    # 实现...

3. 演员修改

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

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

故障排除

连接问题

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

命令执行问题

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

服务器日志

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

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: 参数1的描述
        param2: 参数2的描述
        
    返回：
        包含结果的 JSON 字符串
    """
    # 实现...

定制蓝图交互

您可以通过修改现有函数或创建特定于您演员的新函数来适应服务器以与您的自定义蓝图演员一起工作。

致谢

该项目受到了类似 Claude 的 MCP 集成的启发，特别是由 runeape-sats 制作的原始 Unreal Engine MCP 服务器。特别感谢 Anthropic 团队创造了 Claude 并使这类集成成为可能。