AI导哈

虚幻引擎MCP服务器

一个允许Claude Desktop通过文本提示与Unreal Engine 5.3交互的Python服务器，用于创建和操作3D对象，实现自然语言驱动的3D场景构建和修改。

  • by runeape-sats
  • Python
  • 本地部署
  • 47 星标
  • 更新于
在 GitHub 查看 runeape-sats/unreal-mcp

使用说明

克劳德桌面版虚幻引擎MCP服务器

该存储库包含一个模型上下文协议（MCP）Python服务器，允许Claude Desktop与虚幻引擎5.3交互（通过远程控制API），根据文本提示创建和操作3D对象。这种集成使Claude能够通过自然语言在虚幻引擎中构建和修改3D场景，这是迈向文本到游戏生成技术的早期一步。

当前功能：

  • 使用Claude Desktop文本提示在虚幻引擎编辑器中排列资源
  • 创建用于组装基本体形状的静态网格
  • 查找虚幻项目文件夹中的资源
  • 列出当前级别中的参与者并检查当前编辑器选择
  • 从MCP保存当前级别
  • 调用任意虚幻远程控制函数
  • 通过远程控制属性端点读取和写入虚幻对象属性
  • 使用per命令直接命令行界面 --help 对于非MCP代理
  • 共享城堡工作流、示例代理技能和TLA+用例模型
  • 城堡重置工作流程和一流的城堡MCP工具

快速开始

1.要求

  • Python 3.10+
  • 虚幻引擎5.3，启用远程控制API（插件）

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 → 设置→ 开发者→ 编辑配置 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.启动虚幻引擎

使用您的项目打开虚幻引擎，并确保远程控制API插件已启用。

5.启动MCP客户端（如克劳德桌面）

  • 重新启动Claude Desktop（即，需要在系统托盘中没有Claude图标的干净退出）以加载新配置。您可以通过让Claude在虚幻引擎中创建对象来验证它是否连接。

项目结构

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类中生成演员：

  • 建筑物、道具、人物等。
  • 自定义参数，如基本对象创建

示例提示：“从/Game/CustomAsset/Blueprints/BP_Bench01中的蓝图生成替补席”

场景操纵

修改现有对象：

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

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

编辑的反思与选择

检查当前级别和编辑器选择：

  • 列出当前级别中的所有参与者，可选择使用转换
  • 阅读编辑器中当前选定的演员
  • 从MCP按标签选择演员
  • 在一批更改后保存当前级别

示例提示：“列出标签中带有'Bench'的所有演员，然后选择他们”

通用远程控制访问

服务器现在公开了一个通用的远程控制逃逸窗口，因此您可以访问尚未具有专用MCP工具的虚幻功能：

  • 在任何对象路径上调用任意函数
  • 自动将参与者标签解析为对象路径
  • 读取或写入属性时按类定位组件
  • 通过以下方式读取和写入属性 /remote/object/property

这对于驱动灯、后处理卷、组件、编辑器子系统和自定义Blueprint公开的API非常有用，而无需先添加新的Python包装器。

直接CLI访问

不讲MCP的代理可以使用直接CLI：

  • unreal-mcp-cli --help 列出所有命令
  • unreal-mcp-cli <command> --help 展示了如何使用一个函数
  • 命令直接路由到MCP服务器使用的相同虚幻助手模块

命令示例：

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服务器中创建、验证和重置入口点

城堡工作流的设计使代理可以检查CLI帮助，从基本形状构建城堡，并通过列出参与者来验证结果。 默认情况下，构建工作流会在放置新角色之前删除具有相同计划标签的旧城堡角色。它现在支持布局、大小、调色板和偏航的确定性变化预设，同时保持所需的核心参与者集不变。重置工作流按前缀删除城堡，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：列出具有可选过滤和转换数据的参与者
  • get_selected_actors：检查当前虚幻编辑器选择
  • select_actors：按标签选择演员
  • save_current_level：保存打开的地图
  • remote_call：通过对象路径或参与者标签调用任何虚幻远程控制函数
  • get_object_property：读取任何虚幻对象属性
  • set_object_property：写入任何虚幻对象属性
  • create_basic_castle：直接从MCP构建共享的原始城堡工作流
  • verify_basic_castle：验证通过前缀设置的预期城堡角色
  • reset_basic_castle：通过前缀或严格计划标签删除城堡演员

城堡创建入口点接受 layout, size, palette, origin，以及 yaw 因此，代理可以生成深思熟虑的城堡变体，而验证步骤仍然会检查相同的所需标签。

对于复杂 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 默认情况下替换匹配的旧城堡角色。使用 --keep-existing 只有当你明确地想要重叠的副本时。 命名预设提供受控变化： --layout 改变足迹， --size 改变整体规模， --palette 更改默认颜色，以及 --origin 或 --yaw 更改位置/方向。

测试

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

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

这些测试涵盖了CLI界面、共享城堡计划、TLA+角色集和示例技能连接。

故障排除

连接问题

  • 启动MCP服务器之前，请确保虚幻引擎正在运行
  • 确保在虚幻引擎中启用远程控制API插件
  • 检查是否有其他进程正在使用端口30010
  • 验证您的防火墙没有阻止连接

对象未出现

  • 检查虚幻引擎中的输出日志是否有任何错误
  • 确保创建的对象不会离原点太远（0,0,0）
  • 尝试简化您的请求以隔离问题

日志记录

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

发展

要在开发模式下运行服务器，请执行以下操作：

pip install mcp[cli]
mcp dev unreal_mcp_server.py

贡献

欢迎投稿！这是Claude和虚幻引擎之间的集成，还有很多可以改进的地方：

  • 更好的场景描述自然语言处理
  • 更复杂的对象创建功能
  • 支持更多虚幻引擎功能
  • 改进了错误处理和反馈

许可证

MIT许可证

相关 MCP