Unreal-Blender MCP

Unreal-Blender MCP 是一个统一的服务器，用于通过使用 MCP（机器控制协议）方法的 AI 代理来控制 Blender 和 Unreal Engine。

概述

本项目扩展了 blender-mcp 框架，使其包含对 Unreal Engine 的支持，从而允许像 Claude 和 ChatGPT 这样的 AI 代理通过一个单一的接口同时控制这两个平台。

子模块信息

本项目包含 blender-mcp 作为 Git 子模块。克隆仓库时，请使用以下命令：

# 使用子模块克隆
git clone --recursive https://github.com/tahooki/unreal-blender-mcp.git

# 或者正常克隆，然后初始化子模块
git clone https://github.com/tahooki/unreal-blender-mcp.git
cd unreal-blender-mcp
git submodule update --init --recursive

功能特性

• 统一控制: 单个 MCP 服务器控制 Blender 和 Unreal Engine
• AI 代理集成: 设计用于与 Claude、ChatGPT 和其他 AI 助手一起工作
• Blender 功能: 保留所有 blender-mcp 功能，包括：
  • 场景操作
  • 对象创建和编辑
  • 材质管理
  • PolyHaven 资源集成
  • Hyper3D Rodin 模型生成
• Unreal Engine 功能:
  • 关卡创建和管理
  • 资源导入
  • Python 代码执行
  • 场景操作
• 扩展结构: 轻松扩展 Blender 插件和服务器，同时保持与上游更新的兼容性

架构

该系统由三个主要组件组成：

1. MCP 服务器: 通过端口 8000 上的 SSE（服务器发送事件）与 AI 代理通信的中央枢纽
2. Blender 插件: Blender 内的 Socket 服务器，端口为 8400（标准）或 8401（扩展）
3. Unreal 插件: Unreal Engine 内的 HTTP 服务器，端口为 8500

[AI 代理] <--SSE--> [MCP 服务器 (8300)] 
                        |
                        |--HTTP--> [Blender 插件 (8400)]
                        |
                        |--HTTP--> [Unreal 插件 (8500)]

扩展结构

本项目使用扩展方法来保持与上游更改的兼容性：

• Blender 插件扩展: 扩展原始的 BlenderMCPServer，同时保持原始代码不变
• 服务器扩展: 使用其他工具和 Unreal Engine 集成来增强原始服务器
• 接口工具: 提供用于安装、配置和运行扩展的实用程序

这种方法允许从原始项目轻松更新，而不会产生代码冲突。

逐步安装和设置指南

前提条件

• Python 3.10 或更高版本
• Blender 3.0 或更高版本
• Unreal Engine 5.0 或更高版本
• uv 包管理器（如果还没有，请使用 pip install uv 安装）

1. 克隆仓库

# 使用子模块克隆（推荐）
git clone --recursive https://github.com/tahooki/unreal-blender-mcp.git
cd unreal-blender-mcp

# 或者，如果您已经克隆但没有使用 --recursive：
git clone https://github.com/tahooki/unreal-blender-mcp.git
cd unreal-blender-mcp
git submodule update --init --recursive

2. 设置 Python 环境

# 创建一个虚拟环境并激活它
uv venv
# 在 Windows 上：
.\venv\Scripts\activate
# 在 macOS/Linux 上：
source venv/bin/activate

# 安装项目依赖项
uv pip install -e .

3. 安装 Blender 插件

选择以下选项之一：

选项 A：标准插件（原始 blender-mcp）

1. 打开 Blender
2. 导航到编辑 > 首选项 > 插件
3. 单击“安装...”按钮
4. 浏览并选择 blender-mcp/addon.py 文件
5. 启用“界面：Blender MCP”插件（选中复选框）

选项 B：扩展插件（具有附加功能）

1. 运行扩展安装脚本：

   python -c "from src.unreal_blender_mcp.blender_addon import BlenderAddonManager; BlenderAddonManager().install_to_blender(force=True)"
   

2. 打开 Blender
3. 导航到编辑 > 首选项 > 插件
4. 查找并启用“界面：扩展 Blender MCP”插件（选中复选框）

4. 安装 Unreal Engine 插件

1. 在本项目中找到 UEPythonServer 文件夹
2. 将整个文件夹复制到 Unreal 项目的 Plugins 目录中
   • 如果您的项目没有 Plugins 目录，请创建一个
3. 使用您的项目启动 Unreal Engine
4. 在菜单中导航到编辑 > 插件
5. 查找并启用 Python Server 插件
6. 出现提示时，重新启动 Unreal Engine

5. 启动 MCP 服务器

选择以下选项之一：

选项 A：标准服务器

# 确保您的虚拟环境已激活
python main.py

选项 B：扩展服务器（更多功能）

# 确保您的虚拟环境已激活
python run_extended_server.py

# 可选：自定义服务器选项
python run_extended_server.py --host 127.0.0.1 --port 8080 --log-level DEBUG

6. 启用 Blender 服务器连接

1. 启动 Blender（如果尚未运行）
2. 在 3D 视口中，按 N 打开侧边栏面板
3. 选择相应的选项卡：
   • “BlenderMCP”（如果使用标准插件）
   • “ExtBlenderMCP”（如果使用扩展插件）
4. 单击“启动服务器”按钮
5. 验证服务器是否成功启动（检查控制台输出）

7. 验证 Unreal Engine 连接

1. 在 Unreal Engine 运行且插件已启用的情况下
2. Python 服务器应自动启动
3. 检查输出日志（窗口 > 开发者工具 > 输出日志）以获取任何消息
4. Unreal 插件现在应该可以接收命令了

8. 连接 AI 代理

选项 A：与 Claude for Desktop 集成

将以下内容添加到 Claude for Desktop 的配置中：

{
    "mcpServers": {
        "unreal-blender": {
            "command": "uvx",
            "args": [
                "unreal-blender-mcp"
            ]
        },
        "unreal-blender-ext": {
            "command": "python",
            "args": [
                "/path/to/unreal-blender-mcp/run_extended_server.py"
            ]
        }
    }
}

将 /path/to/ 替换为您的实际项目路径。

选项 B：与 Cursor 集成

1. 打开 Cursor 设置

2. 导航到 MCP 部分

3. 添加以下命令：

   • 标准服务器：uvx unreal-blender-mcp
   • 扩展服务器：python /path/to/unreal-blender-mcp/run_extended_server.py

   将 /path/to/ 替换为您的实际项目路径。

选项 C：与其他 AI 工具集成

请参阅您的 AI 工具的文档，了解如何与 MCP 服务器集成，并将其指向：

• MCP 服务器 URL：http://localhost:8000（或指定的自定义端口）

9. 测试系统

所有组件运行后：

1. 使用您的 AI 代理与 Blender 交互，要求它：

   • 创建一个简单的立方体或球体
   • 修改对象属性
   • 创建材质

2. 使用您的 AI 代理与 Unreal Engine 交互，要求它：

   • 创建一个新关卡
   • 放置资源
   • 修改场景属性

3. 尝试涉及两个平台协同工作的更复杂的操作

故障排除

如果您遇到问题：

1. 检查所有服务器是否正在运行（MCP、Blender、Unreal）
2. 验证端口配置是否匹配（默认：MCP 为 8000，Blender 为 8400/8401，Unreal 为 8500）
3. 检查控制台输出中的错误消息
4. 以正确的顺序重新启动组件：先启动 MCP 服务器，然后启动 Blender，然后启动 Unreal Engine

有关开发和扩展系统的更多详细信息，请参阅 项目文档 和 workflow 目录。

比较：标准 vs 扩展

功能	标准服务器	扩展服务器
Blender 控制	✅	✅
Unreal 控制	✅	✅
自定义 Blender 命令	❌	✅
增强的场景信息	❌	✅
自动功能检测	❌	✅
上游兼容性	✅	✅

选择标准服务器以获得基本功能，或选择扩展服务器以获得高级功能。

开发

有关详细的开发信息，请参阅 项目文档 和 workflow 目录。

要扩展本项目：

• 要添加新的 Blender 插件功能：修改 src/unreal_blender_mcp/blender_addon/extended_addon.py
• 要添加新的服务器工具：修改 src/unreal_blender_mcp/server_extension/extended_server.py

许可证

本项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。

致谢

• 本项目基于 Siddharth Ahuja 的 blender-mcp 构建。

未来发展

计划在未来版本中进行以下改进：

结构化的 Unreal Engine API

目前，Unreal Engine 通信主要依赖于直接 Python 代码执行。计划的增强功能是实现类似于 Blender 集成的结构化 API：

• 为常见的 Unreal Engine 操作创建预定义函数
• 实现适当的错误处理和验证
• 通过限制执行范围来提高安全性
• 提高操作的稳定性和可预测性
• 在添加结构的同时保持向后兼容性

此增强功能将在两个引擎中创建更一致的体验，并提高系统的整体可靠性。有关此计划开发的更多详细信息，请参阅 workflow 文档。