UnrealMCP 插件

高度开发中 (WIP)

我正在添加更多工具并清理代码库， 我计划允许在主插件之外轻松扩展工具

这仍然处于非常早期的开发阶段，我需要清理很多东西!!!!!

另外，我只使用 Windows，所以我不知道这在 Mac/Unix 上如何设置

概述

UnrealMCP 是一个非官方的虚幻引擎（Unreal Engine）插件，旨在通过 AI 工具控制虚幻引擎。它在虚幻引擎内实现了机器控制协议（Machine Control Protocol, MCP），允许外部 AI 系统与虚幻环境进行程序化交互和操控。

我几天前才了解到 MCP，所以我还不太熟悉它，仍在学习中，因此初期可能比较粗糙。 我是参考 https://github.com/ahujasid/blender-mcp 实现的，它依赖桌面版 Claude。它可能支持其他模型，也可能不支持，如果你进行了实验，请告诉我！

⚠️ 免责声明

此插件允许 AI 代理直接修改你的虚幻引擎项目。虽然它是一个强大的工具，但也存在风险：

• AI 代理可能会对你的项目做出意外更改
• 文件可能会被意外删除或修改
• 项目设置可能会被更改
• 资产可能会被覆盖

重要安全措施：

1. 始终与你的项目一起使用版本控制系统（如 Git 或 Perforce）
2. 定期备份你的项目
3. 首先在单独的项目中测试该插件
4. 提交更改前请审查它们

使用此插件即表示你确认：

• 你对项目所做的任何更改负全责
• 插件作者不对 AI 代理造成的任何损坏、数据丢失或问题负责
• 你使用此插件的风险自负

功能

• 用于远程控制虚幻引擎的 TCP 服务器实现
• 基于 JSON 的命令协议，用于 AI 工具集成
• 编辑器 UI 集成，方便访问 MCP 功能
• 全面的场景操作能力
• 用于客户端交互的 Python 辅助脚本

路线图

这是我在 2025 年 3 月 14 日计划中的开发内容。 我还不确定哪些是可行的，理论上什么都可以，但这取决于集成的 LLM（大语言模型）利用这些工具的能力有多好。

• 基本操作正常工作
• Python 正常工作
• 材质
• 用户扩展（进行中）
• 资产工具
• 蓝图 (Blueprints)
• Niagara 视觉效果 (VFX)
• MetaSound
• 地形 (Landscape)（我可能会暂时搁置这一点，因为 Epic 提到他们将更新地形工具）
• 建模工具
• 程序化内容生成 (PCG)

要求

• 虚幻引擎 5.5（我仅在此版本上测试过，可能在早期版本上也能工作，但没有官方支持）
• 为虚幻引擎配置的 C++ 开发环境
• Python 3.7+ 用于客户端脚本编写
• 用于运行命令的模型，测试中我使用的是桌面版 Claude https://claude.ai/download

安装

1. 将此仓库克隆到你的虚幻项目的 Plugins 目录中：

   git clone https://github.com/kvick-games/UnrealMCP.git Plugins/UnrealMCP
   

   项目路径应匹配以下模式： ...\UNREAL_PROJECT\Plugins\UnrealMCP\

2. 重新生成你的项目文件（右键点击 .uproject 文件并选择“生成 Visual Studio 项目文件”）

3. 在你使用的任何 IDE 中构建项目，我使用 Rider，Visual Studio 也可以（正在制作发布版）

4. 打开你的项目并在“编辑 > 插件 > UnrealMCP"中启用该插件

5. 在虚幻中启用 Python 插件

6. 运行 setup_unreal_mcp.bat（随着更多人尝试，我可能需要对此文件进行一些修复）

7. 目前我仅使用桌面版 Claude 进行了测试，因此请按照以下说明继续操作

配合桌面版 Claude 使用

你需要找到桌面版 Claude 的安装目录。找到 claude_desktop_config.json 并添加一个条目，使其看起来像这样：

{
    "mcpServers": {
        "unreal": {
            "command": "C:\\UnrealMCP_Project\\Plugins\\UnrealMCP\\MCP\\run_unreal_mcp.bat",
            "args": []
        }
    }
}

在命令字段中输入指向脚本的插件目录路径："run_unreal_mcp.bat" 此脚本位于 ../plugin_root_directory/MCP/run_unreal_mcp.bat 内

你可以参考此链接获取更多信息： https://modelcontextprotocol.io/quickstart/user

要查找桌面版 Claude 的安装路径，你可以进入设置并点击“编辑配置” 在我的 Windows PC 上，路径是： C:\Users\USERNAME\AppData\Roaming\Claude

用法

在虚幻编辑器中

启用插件后，你会在编辑器工具栏按钮中找到 MCP 控件。

TCP 服务器可以从这里启动/停止。 检查输出日志下的 LogMCP 过滤器以获取额外信息。

一旦从编辑器确认服务器已启动并运行。 打开桌面版 Claude，确保工具已成功启用，让 Claude 在虚幻中工作。

目前仅支持基本操作，创建对象、修改它们的变换、获取场景信息和运行 Python 脚本。 由于我认为虚幻 Python 方面的示例不多，Claude 在使用虚幻 Python 时经常出错，但让它运行通常能解决问题。 我非常想改进这方面的工作方式，但这对于向虚幻添加功能来说是容易实现的功能点。

客户端集成

使用 MCP 目录中提供的 Python 脚本来连接和控制你的虚幻引擎实例：

from unreal_mcp_client import UnrealMCPClient

# 连接到虚幻 MCP 服务器
client = UnrealMCPClient("localhost", 13377)

# 示例：在场景中创建一个立方体
client.create_object(
    class_name="StaticMeshActor",
    asset_path="/Engine/BasicShapes/Cube.Cube",
    location=(0, 0, 100),
    rotation=(0, 0, 0),
    scale=(1, 1, 1),
    name="MCP_Cube"
)

命令参考

插件支持各种场景操作命令：

• get_scene_info: 检索当前场景的信息
• create_object: 在场景中生成新对象
• delete_object: 从场景中移除对象
• modify_object: 更改现有对象的属性
• execute_python: 在虚幻的 Python 环境中运行 Python 命令
• 更多即将推出...

有关完整的命令参考，请参阅 Docs 目录中的文档。

安全考虑

• MCP 服务器默认接受来自任何客户端的连接
• 开发时将服务器暴露限制在本地主机 (localhost)
• 验证所有传入的命令以防止注入攻击

故障排除

• 确保虚幻引擎 (Unreal Engine) 正在运行并加载了 MCP 插件。
• 检查 Claude for Desktop 中的日志以查看 stderr (标准错误输出) 输出。
• 在 Discord 上联系我，我刚刚创建了服务器，但我会定期检查 Discord (Dreamatron Studios): https://discord.gg/abRftdSe

项目结构

• Source/UnrealMCP/: 核心插件实现
  • Private/: 内部实现文件
  • Public/: 公共头文件
• Content/: 插件资源
• MCP/: Python 客户端脚本和示例
• Resources/: 图标和其他资源

许可证

MIT 许可证

版权所有 (c) 2025 kvick

特此免费授予任何获得本软件副本及相关文档文件（“软件”）的人，在不加限制地使用、复制、修改、合并、出版、分发、再许可及/或出售本软件副本的权利，并允许向其提供本软件的人员这样做，但须符合以下条件：

上述版权声明和本权限声明应包含在所有副本或软件的主要部分中。

本软件按“原样”提供，不提供任何形式的保证，无论是明示的还是暗示的，包括但不限于对适销性、特定用途适用性和非侵权的保证。在任何情况下，作者或版权持有人均不对因使用本软件或在本软件的其他交易中使用本软件而产生的任何索赔、损害或其他责任负责，无论是在合同诉讼、侵权诉讼还是其他方面。

致谢

• 创建者：kvick
• X: @kvickart

感谢测试人员！！！

• https://github.com/TheMurphinatur

• @sidahuj 提供的灵感

贡献指南

欢迎贡献，但我需要先花点时间理清思路并进行清理，哈哈

UnrealMCP 快速上手指南

UnrealMCP 是一个非官方的 Unreal Engine 插件，旨在通过机器控制协议（MCP）让外部 AI 系统直接控制并操作虚幻引擎。目前该工具处于早期开发阶段（WIP），仅官方测试支持 Windows 环境。

⚠️ 重要风险提示：此插件允许 AI 代理直接修改您的工程。可能导致资产丢失、设置更改或意外删除。使用前请务必：

1. 启用版本控制（如 Git 或 Perforce）。
2. 备份项目文件。
3. 在独立项目中先行测试。
4. 作者不对任何数据损失负责。

环境准备

• 操作系统：Windows（作者仅在此环境下测试，Mac/Unix 未经验证）。
• 引擎版本：Unreal Engine 5.5（可能兼容更早版本，但无官方支持）。
• 开发环境：配置好的 C++ 开发环境（用于编译插件）。
• 脚本语言：Python 3.7+（用于客户端交互）。
• AI 模型：推荐使用 Claude for Desktop（基于 README 测试环境）。

安装步骤

1. 克隆插件 将仓库克隆至您的 Unreal 项目的 Plugins 目录下：

   git clone https://github.com/kvick-games/UnrealMCP.git Plugins/UnrealMCP
   

   确保路径符合以下结构： ...\UNREAL_PROJECT\Plugins\UnrealMCP\

2. 生成项目文件 右键点击 .uproject 文件，选择 "Generate Visual Studio project files"（生成 Visual Studio 项目文件）。

3. 编译项目 在您使用的 IDE（如 Rider 或 Visual Studio）中构建项目。

4. 启用插件 打开项目，进入 Edit > Plugins，搜索并启用 UnrealMCP。同时确保已启用 Python 相关插件。

5. 运行初始化脚本 在项目根目录运行以下批处理文件：

   .\setup_unreal_mcp.bat
   

6. 配置 Claude 连接 找到您的 Claude for Desktop 配置文件 claude_desktop_config.json（通常在 C:\Users\USERNAME\AppData\Roaming\Claude），添加如下配置项，注意替换为您的实际插件路径：

   {
       "mcpServers": {
           "unreal": {
               "command": "C:\\UnrealMCP_Project\\Plugins\\UnrealMCP\\MCP\\run_unreal_mcp.bat",
               "args": []
           }
       }
   }
   

基本使用

编辑器端操作

1. 启动 Unreal Editor，在工具栏中找到 MCP 控制按钮。
2. 点击按钮启动 TCP 服务器。
3. 在输出日志窗口过滤 LogMCP 以查看服务器状态信息。

与 AI 交互

1. 打开 Claude for Desktop，确认工具已成功启用。
2. 向 Claude 发送指令（例如：“在场景中创建一个立方体”）。
3. 当前支持的基础功能包括：创建对象、修改变换、获取场景信息、运行 Python 脚本。

客户端集成示例

您也可以使用提供的 Python 脚本直接连接并控制引擎实例：

from unreal_mcp_client import UnrealMCPClient

# 连接到 Unreal MCP 服务器
client = UnrealMCPClient("localhost", 13377)

# 示例：在场景中创建一个立方体
client.create_object(
    class_name="StaticMeshActor",
    asset_path="/Engine/BasicShapes/Cube.Cube",
    location=(0, 0, 100),
    rotation=(0, 0, 0),
    scale=(1, 1, 1),
    name="MCP_Cube"
)