unreal-engine-mcp-server-for-claude-desktop

🚀 用于Claude桌面的Unreal Engine MCP服务器

本项目提供了一个MCP Python服务器，让Claude Desktop能通过文本提示与Unreal Engine 5.3（借助远程控制API）进行交互，实现3D对象的创建与操作。这种集成让Claude可以用自然语言在Unreal Engine里构建和修改3D场景，是迈向文字到游戏生成技术的重要一步。

🚀 快速开始

🔍 需求

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

📦 安装

克隆仓库并安装所需的包：

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

⚙️ 配置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": {}
    }
  }
}

▶️ 启动Unreal Engine

启动Unreal Engine并确保远程控制API插件已启用。

▶️ 启动Claude Desktop

运行以下命令以启动MCP服务器：

mcp run unreal_mcp_server.py

📁 项目结构

• unreal_mcp_server.py：负责与Claude进行交互。
• commands/：定义了各种功能命令，例如创建几何体、移动对象等。

✨ 主要特性

🔨 基本操作

1. 创建几何体：
   • 使用create_cube()创建立方体。
   • 使用create_sphere()创建球体。
   • 使用create_cylinder()创建圆柱体。
2. 变换操作：
   • 使用set_position(x, y, z)设置对象位置。
   • 使用set_rotation(x, y, z)设置对象旋转角度。
   • 使用set_scale(x, y, z)调整对象缩放比例。
3. 删除对象：
   • 使用delete_object()删除指定对象。

💪 进阶功能

• 批量操作：支持同时对多个对象执行相同操作，如移动、旋转等。
• 场景保存/加载：允许保存当前场景并重新加载之前保存的场景。
• 材质修改：可调整对象的材质属性，如颜色、纹理等。

💻 使用示例

📋 基础用法

# 创建一个红色立方体
cube = create_cube()
set_color(cube, (1, 0, 0))

# 创建一个蓝色球体
sphere = create_sphere()
set_color(sphere, (0, 0, 1))

📈 高级用法

# 将立方体移动到指定位置
set_position(cube, (5, 0, 0))

# 绕Y轴旋转90度
set_rotation(cube, (0, 90, 0))

# 调整缩放比例
set_scale(cube, (2, 1, 1))

🛠️ 故障排除

🔌 连接问题

• 确保Unreal Engine和Claude Desktop均已启动且网络连接正常。
• 检查防火墙设置，确保端口未被阻止。

🎨 对象未显示

• 检查Unreal Engine的日志文件以获取错误信息。
• 确保对象创建位置在合理范围内，避免过于远离原点(0,0,0)。
• 尝试简化请求以隔离问题。

🛠️ 开发

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

pip install mcp[cli]
mcp dev unreal_mcp_server.py

👥 贡献

欢迎参与贡献！本项目是Claude与Unreal Engine的集成项目，还有诸多可改进之处：

• 提高自然语言处理能力以更好地理解场景描述。
• 增加更多复杂的对象创建功能。
• 支持更多的Unreal Engine特性。
• 改进错误处理和反馈机制。

📄 许可证

MIT许可