Unreal-Blender MCP

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

概述

该项目扩展了 blender-mcp 框架，增加了对 Unreal Engine 的支持，使得像 Claude 和 ChatGPT 这样的 AI 代理能够通过单一接口同时控制这两个平台。

子模块信息

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

# Clone with submodules
git clone --recursive https://github.com/tahooki/unreal-blender-mcp.git

# Or clone normally and then initialize submodules
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 服务器：中心枢纽，通过 SSE（服务器发送事件）在端口 8000 上与 AI 代理通信
2. Blender 插件：Blender 内部的套接字服务器，在端口 8400（标准）或 8401（扩展）
3. Unreal 插件：Unreal Engine 内部的 HTTP 服务器，在端口 8500

[AI Agent] <--SSE--> [MCP Server (8300)] 
                        |
                        |--HTTP--> [Blender Addon (8400)]
                        |
                        |--HTTP--> [Unreal Plugin (8500)]

扩展结构

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

• Blender 插件扩展：在保持原始代码完整的情况下扩展原始的 BlenderMCPServer
• 服务器扩展：通过额外工具和 Unreal Engine 集成增强原始服务器
• 接口工具：提供安装、配置和运行扩展的实用程序

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

安装和设置逐步指南

先决条件

• Python 3.10 或更高版本
• Blender 3.0 或更高版本
• Unreal Engine 5.0 或更高版本
• uv 包管理器（如果你没有安装，可以通过 pip install uv 安装）

1. 克隆仓库

# Clone with submodules (recommended)
git clone --recursive https://github.com/tahooki/unreal-blender-mcp.git
cd unreal-blender-mcp

# Or if you already cloned without --recursive:
git clone https://github.com/tahooki/unreal-blender-mcp.git
cd unreal-blender-mcp
git submodule update --init --recursive

2. 设置 Python 环境

# Create a virtual environment and activate it
uv venv
# On Windows:
.\venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

# Install project dependencies
uv pip install -e .

3. 安装 Blender 插件

选择以下选项之一：

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

1. 打开 Blender
2. 导航到 编辑 > 首选项 > 插件
3. 点击“安装...”按钮
4. 浏览并选择 blender-mcp/addon.py 文件
5. 启用 "Interface: 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. 查找并启用“Interface: Extended Blender MCP”插件（勾选框）

4. 安装Unreal Engine插件

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

5. 启动MCP服务器

请选择以下任一选项：

选项A：标准服务器

# Make sure your virtual environment is activated
python main.py

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

# Make sure your virtual environment is activated
python run_extended_server.py

# Optional: Customize server options
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集成

将以下内容添加到桌面版Claude的配置中：

{
    "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

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

对比：标准版与扩展版

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

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

开发

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

要扩展此项目：

• 要添加新的 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 操作创建预定义函数
• 实现适当的错误处理和验证
• 通过限制执行范围来提高安全性
• 提高操作的稳定性和可预测性
• 在增加结构的同时保持向后兼容性

这项改进将使两个引擎之间的体验更加一致，并提高系统的整体可靠性。有关此计划开发的更多细节，请参阅 工作流文档。