Py Ue5 MCP Server

py-ue5-mcp服务器

适用于Claude的虚幻引擎5 MCP服务器

此存储库包含一个模型上下文协议（MCP）Python服务器，使Claude能够通过自然语言与虚幻引擎5进行交互。通过利用远程控制API，此集成允许您通过与Claude的对话直接在虚幻引擎中创建、操作和控制3D对象和蓝图参与者。

概述

此MCP服务器弥合了Claude的自然语言处理能力和虚幻引擎强大的3D环境之间的差距。用户可以简单地描述他们想在虚幻引擎中创建或修改什么，Claude将解释这些请求并通过MCP服务器执行适当的操作。

主要特点

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

需求

• Python 3.10+
• 启用远程控制API插件的虚幻引擎5.x
• 克劳德桌面（Windows）
• 虚幻引擎基础知识

安装

1.设置存储库

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

2.配置克劳德桌面

1. 打开克劳德桌面
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.准备虚幻引擎

1. 打开虚幻引擎和您的项目
2. 确保远程控制API插件已启用：

- Edit → 插件→ 搜索“远程控制API” - 检查是否已启用，必要时重新启动编辑器

用法

入门指南

1. 使用您的项目启动虚幻引擎
2. 启动Claude Desktop（如果它已经在运行，请重新启动）
3. 开始与Claude聊天，讨论如何在虚幻引擎中创建或修改内容

示例提示

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

• 在0、100、50的位置堆雪人
• “现场堆雪人一家”
• “修改中心雪人的比例，使其更大”
• “将雪人移动到位置100、200、0”
• “将雪人旋转45度”
• “获取场景中所有演员的列表”

了解单位

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

• 1个虚幻单位=1厘米
• 标准雪人的尺寸约为350cm×350cm（3.5m×3.5m）
• 定位和缩放都与这个基于厘米的系统有关

运作原理

技术实现

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

1.MCP服务器框架

服务器是使用FastMCP构建的，它在Claude和虚幻引擎之间建立了一个双向通信通道。主要部件有：

# 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.连接虚幻引擎

服务器通过远程控制API连接到虚幻引擎，这是一个运行在虚幻内部的内置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.演员操纵

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

# 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
}

每个操作都作为对虚幻引擎远程控制API的HTTP请求执行，后者以JSON格式返回结果。

特色功能

1.雪人家庭创作

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

• 创建一个初始雪人演员
• 复制它以创建另外两个具有不同位置、旋转和比例的雪人
• 把他们安排成一个家庭

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

2.蓝图演员复制

服务器可以使用场景中的本地Blueprint函数复制现有角色：

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.演员修改

服务器支持修改现有参与者的任何属性：

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

故障排除

连接问题

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

命令执行问题

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

服务器日志

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

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() 装饰器
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...

自定义蓝图交互

您可以通过修改现有函数或创建特定于您的参与者的新函数，使服务器适应您的自定义蓝图参与者。

致谢

这个项目的灵感来自Claude的类似MCP集成，特别是runeape sats的原始虚幻引擎MCP服务器。特别感谢Anthropic团队创建了Claude并实现了这些集成。