Unreal Engine MCP Server for Claude Desktop

此仓库包含一个模型上下文协议（MCP）Python服务器，允许Claude Desktop通过远程控制API与Unreal Engine 5.3进行交互，基于文本提示创建和操作3D对象。这种集成使Claude能够通过自然语言在Unreal Engine中构建和修改3D场景，这是迈向文本到游戏生成技术早期步骤的一部分。

当前功能：

• 使用Claude Desktop的文本提示来安排Unreal Engine编辑器中的资产
• 创建静态网格以组装基本形状
• 查找Unreal项目文件夹中的资产

快速开始

1. 要求

• Python 3.10+
• 启用了远程控制API插件的Unreal Engine 5.3
• Claude Desktop（Windows）

2. 安装

克隆仓库并安装所需包：

git clone https://github.com/runeape-sats/unreal-mcp.git
cd unreal-mcp
pip install uv mcp requests

3. 配置Claude Desktop

前往Claude Desktop → 文件 → 设置 → 开发者 → 编辑配置 claude_desktop_config.json 并添加以下内容，调整路径指向你的本地仓库：

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

如果你已经配置了其他MCP服务器（如blender-mcp），可能需要禁用它们以确保不会冲突。

4. 启动Unreal Engine

打开带有项目的Unreal Engine，并确保启用了远程控制API插件。

5. 启动Claude Desktop

重启Claude Desktop（即需要干净退出，系统托盘中没有Claude图标）以加载新配置。你可以通过让Claude在Unreal Engine中创建对象来验证是否已连接。

项目结构

服务器组织成几个模块：

• unreal_mcp_server.py - 注册MCP工具的主要入口点
• unreal_connection.py - 处理与Unreal Engine的通信
• unreal_actors.py - 创建和操作演员的功能
• unreal_assets.py - 处理资产和级别信息的功能
• unreal_utils.py - 工具函数和常量

功能

基本对象创建

使用各种参数创建基本形状：

• 立方体、球体、圆柱体、平面、圆锥体
• 自定义位置、旋转、缩放
• 自定义颜色和材质

示例提示："在位置100, 200, 50处创建一个红色立方体"

蓝图演员创建

从蓝图类生成演员：

• 建筑物、道具、角色等
• 如基本对象创建中的自定义参数

示例提示："从蓝图/Game/CustomAsset/Blueprints/BP_Bench01生成一个长凳"

场景操作

修改现有对象：

• 更改位置、旋转、缩放
• 调整颜色和材质
• 切换可见性

示例提示："将立方体移动到位置0, 0, 100并旋转45度"

资产发现

搜索并列出可用资产：

• 按资产类型过滤（蓝图、网格、材质）
• 在特定路径中搜索
• 查找匹配某些术语的资产

示例提示："列出项目中的所有长凳静态网格"

示例提示

这里有一些你可以用来与Claude互动的示例提示：

在位置0, 100, 50处创建一个蓝色球体，缩放比例为2, 2, 2

创建一个场景，在0,0,0处有一个红色立方体，在100,0,0处有一个绿色球体，在0,100,0处有一个蓝色圆柱体

列出/Game/CustomAsset文件夹中的所有蓝图资产

获取当前级别的信息

创建一个圆柱体，然后将其颜色更改为黄色

故障排除

连接问题

• 确保在启动MCP服务器之前Unreal Engine正在运行
• 确保Unreal Engine中启用了远程控制API插件
• 检查是否有其他进程使用端口30010
• 验证防火墙未阻止连接

对象未出现

• 检查Unreal Engine中的输出日志是否有任何错误
• 确保对象不是在离原点（0,0,0）太远的地方创建
• 尝试简化请求以隔离问题

日志记录

服务器将详细信息记录到控制台。如果遇到问题，请检查日志中的错误消息和跟踪。

开发

要在开发模式下运行服务器：

pip install mcp[cli]
mcp dev unreal_mcp_server.py

贡献

欢迎贡献！这是一个Claude和Unreal Engine之间的集成，有很多可以改进的地方：

• 改进场景描述的自然语言处理
• 更复杂的对象创建能力
• 支持更多的Unreal Engine特性
• 改进错误处理和反馈

许可证

MIT许可证