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-m
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 内部的端口 8400（标准）或 8401（扩展）套接字服务器
3. Unreal 插件：Unreal Engine 内部的端口 8500 HTTP 服务器

[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 集成

向桌面 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

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

比较：标准 vs 扩展

功能	标准服务器	扩展服务器
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 操作创建预定义函数
• 实现正确的错误处理和验证
• 通过限制执行范围提高安全性
• 提高操作的稳定性和可预测性
• 在添加结构的同时保持向后兼容性

此改进将在两个引擎之间创造更加一致的体验，并提高系统的整体可靠性。请参阅 工作流程文档 以获取更多关于此计划开发的详细信息。