Unreal Engine MCP Server for Claude Desktop

面向 Claude Desktop 的 Unreal Engine MCP 服务

此仓库包含一个 Model Context Protocol (MCP) Python 服务，可让 Claude Desktop 与 Unreal Engine 5.3（通过 Remote Control API）交互，根据文本提示创建和操控 3D 对象。此集成支持通过自然语言让 Claude 在 Unreal Engine 中构建和修改 3D 场景，是迈向文本生成游戏技术的早期一步。

当前功能：

• 使用 Claude Desktop 文本提示在 Unreal Engine 编辑器中摆放资产
• 创建静态网格体以组合基本形状
• 查找 Unreal 项目文件夹中的资产
• 列出当前关卡中的 Actor，并检查当前编辑器选区
• 从 MCP 保存当前关卡
• 调用任意 Unreal Remote Control 函数
• 通过 Remote Control 属性端点读取和写入 Unreal 对象属性
• 提供直接命令行接口，并为非 MCP Agent 提供逐命令 --help
• 共享城堡工作流、示例 Agent 技能和 TLA+ 用例模型
• 城堡重置工作流和一流的城堡 MCP 工具

快速开始

1. 要求

• Python 3.10+
• 启用了 Remote Control API（插件）的 Unreal Engine 5.3

2. 安装

克隆仓库并以可编辑模式安装：

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

此操作会安装 unreal-mcp-cli 命令，并使 unreal_mcp 包可导入。

3. 配置 MCP 服务

• 如果你使用 Claude Desktop → File → Settings → Developer → Edit Config 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 和你的项目，并确保已启用 Remote Control API 插件。

5. 启动 MCP 客户端（例如 Claude Desktop）

• 重启 Claude Desktop（即，完全退出，确保系统托盘中不再显示 Claude 图标），以加载新配置。你可以让 Claude 在 Unreal Engine 中创建对象，以验证是否已连接。

项目结构

unreal_mcp/              # Core package
  __init__.py
  server.py              # MCP server — registers all tools
  cli.py                 # Direct CLI with subcommands and --help
  connection.py          # HTTP connection to Unreal Remote Control API
  actors.py              # Actor create / modify / delete helpers
  assets.py              # Asset discovery and level info
  remote.py              # Generic Remote Control and editor helpers
  utils.py               # Shared constants and parsing utilities

examples/                # Example workflows (separate from core)
  castle/
    workflow.py           # Castle build / verify / reset workflow
    assets/castle-plan.json
    specs/CastleConstruction.tla

tests/                   # Unit tests (20 tests)
  test_castle_assets.py
  test_castle_workflow.py
  test_unreal_cli.py

根目录下的垫片模块（unreal_mcp_server.py、unreal_cli.py 等）会从 unreal_mcp.* 重新导出内容，以保持向后兼容。

功能

基本对象创建

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

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

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

Blueprint Actor 创建

从 Blueprint 类生成 Actor：

• 建筑、道具、角色等
• 自定义参数，与基本对象创建相同

提示词示例：“从路径为 /Game/CustomAsset/Blueprints/BP_Bench01 的 blueprint 生成一张长凳”

场景操控

修改现有对象：

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

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

编辑器内省与选区

检查当前关卡和编辑器选区：

• 列出当前关卡中的所有 Actor，可选是否包含变换信息
• 读取编辑器中当前选中的 Actor
• 通过 MCP 按标签选择 Actor
• 批量更改后保存当前关卡

提示词示例：“列出标签中包含 ‘Bench’ 的所有 Actor，然后选中它们”

通用远程控制访问

服务器现在提供了通用的 Remote Control 备用通道，让你可以访问尚未配备专用 MCP 工具的 Unreal 功能：

• 对任意对象路径调用函数
• 自动将 Actor 标签解析为对象路径
• 读取或写入属性时，按类指定目标组件
• 通过 /remote/object/property 读取和写入属性

无需先添加新的 Python 封装，就能借此驱动灯光、后期处理体积、组件、编辑器子系统以及自定义 Blueprint 暴露的 API。

直接 CLI 访问

不支持 MCP 的 Agent 可以改用直接 CLI：

• unreal-mcp-cli --help 列出所有命令
• unreal-mcp-cli <command> --help 显示某个函数的用法
• 各命令会直接调用 MCP 服务所用的同一组 Unreal 辅助模块

命令示例：

unreal-mcp-cli commands
unreal-mcp-cli list-level-actors --kwargs "filter=Castle max_results=20"
unreal-mcp-cli remote-call --kwargs "actor_label=SkyLight function_name=GetActorLocation"

如果尚未安装可编辑脚本，请使用 .venv\Scripts\python.exe unreal_cli.py --help。

城堡技能与 TLA+ 模型

仓库现在包含：

• 可复用的城堡规划文件：examples/castle/assets/castle-plan.json
• 示例技能：.github/skills/unreal-castle-builder/SKILL.md
• TLA+ 用例模型：examples/castle/specs/CastleConstruction.tla
• CLI 和 MCP 服务中专用的城堡创建、验证和重置入口

城堡工作流旨在让 Agent 检查 CLI 帮助信息、用基本形状建造城堡，并通过列出 Actor 来验证结果。 默认情况下，建造工作流会先移除标签与规划中标签相同的旧城堡 Actor，再放置新 Actor。现在，它支持对布局、尺寸、配色和偏航角使用确定性的变化预设，同时保留相同的必需核心 Actor 集合。重置工作流会按前缀删除城堡；TLA+ 模型现在也覆盖了重试、重建和变体选择，以及成功完成的情况。

资源发现

搜索并列出可用资源：

• 按资源类型筛选（蓝图、网格、材质）
• 在指定路径中搜索
• 查找符合特定词语的资源

提示词示例：“列出项目中的所有长凳静态网格体”

示例提示词

以下是一些可与 Claude 搭配使用的示例提示词：

Create a blue sphere at position 0, 100, 50 with scale 2, 2, 2

Create a scene with a red cube at 0,0,0, a green sphere at 100,0,0, and a blue cylinder at 0,100,0

List all blueprint assets in the /Game/CustomAsset folder

Get information about the current level

Create a cylinder and then change its color to yellow

List all actors whose label contains Bench

Show me the actors currently selected in the editor

Select actors Bench_A, Bench_B, and Bench_C

Save the current level

Set the intensity property on actor KeyLight to 5000

Call a remote function on actor SkyLight to recapture the scene

Use the CLI help for the castle workflow

Create a castle from basic shapes with prefix SkillCastle

Create a grand sandstone courtyard castle at a new placement

Verify the SkillCastle actors exist in the level

Reset the SkillCastle actors after verification

新增 MCP 工具

除了现有的生成、修改、删除和资源查找工具外，服务器现在还提供：

• list_level_actors：列出 Actor，可选择是否筛选并包含变换数据
• get_selected_actors：检查当前 Unreal Editor 中的选择
• select_actors：按标签选择 Actor
• save_current_level：保存当前打开的地图
• remote_call：按对象路径或 Actor 标签调用任意 Unreal Remote Control 函数
• get_object_property：读取任意 Unreal 对象属性
• set_object_property：写入任意 Unreal 对象属性
• create_basic_castle：直接通过 MCP 构建共享的基础图元城堡工作流
• verify_basic_castle：按前缀验证预期的城堡 Actor 集合
• reset_basic_castle：按前缀或严格匹配的规划标签删除城堡 Actor

城堡创建入口接受 layout、size、palette、origin 和 yaw，让 Agent 能生成有意设计的城堡变体，同时验证步骤仍会检查相同的必需标签。

对于复杂的 remote_call 或属性写入，建议使用 JSON 格式的参数，以便在解析时完整保留嵌套参数结构。

CLI 设置

在虚拟环境中以可编辑模式安装项目，即可使用 unreal-mcp-cli 命令：

.venv\Scripts\python.exe -m pip install -e .
unreal-mcp-cli --help

常用命令模式：

unreal-mcp-cli create-static-mesh-actor --help
unreal-mcp-cli create-basic-castle --prefix SkillCastle --layout courtyard --size grand --palette sandstone
unreal-mcp-cli create-basic-castle --prefix Bastion01 --origin 6000,1200,0 --yaw 45 --palette obsidian
unreal-mcp-cli list-level-actors --kwargs "filter=SkillCastle max_results=40"
unreal-mcp-cli verify-basic-castle --prefix SkillCastle
unreal-mcp-cli reset-basic-castle --prefix SkillCastle --strict-plan

create-basic-castle 默认会替换匹配的旧城堡 Actor。只有明确需要重叠的重复对象时，才使用 --keep-existing。 命名预设可提供受控的变化：--layout 更改占地布局，--size 更改整体比例，--palette 更改默认颜色，--origin 或 --yaw 则更改放置位置或朝向。

测试

使用以下命令运行自动化测试：

.venv\Scripts\python.exe -m unittest discover -s tests -v

这些测试涵盖 CLI 接口、共享城堡计划、TLA+ actor 集合和示例技能接线。

故障排除

连接问题

• 启动 MCP 服务前，请确保 Unreal Engine 正在运行
• 确保 Unreal Engine 中已启用 Remote Control API 插件
• 检查端口 30010 是否被其他进程占用
• 确认防火墙未阻止连接

对象未显示

• 检查 Unreal Engine 中的输出日志，查看是否有错误
• 确保对象创建位置没有离原点（0,0,0）太远
• 尝试简化请求，以便定位问题

日志记录

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

开发

要以开发模式运行服务：

pip install mcp[cli]
mcp dev unreal_mcp_server.py

贡献

欢迎贡献！这是 Claude 与 Unreal Engine 之间的集成，还有很多可以改进之处：

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

许可证

MIT 许可证