AI导哈

虚幻引擎与Blender控制协议

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

  • by tahooki
  • Python
  • 本地部署
  • 21 星标
  • 更新于
在 GitHub 查看 tahooki/unreal-blender-mcp

使用说明

虚幻混合器MCP

虚幻Blender MCP是一个统一的服务器，用于通过使用MCP（机器控制协议）方法的AI代理控制Blender和虚幻引擎。

概述

该项目扩展了 搅拌机mcp 该框架将包括对虚幻引擎的支持，允许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和虚幻引擎
  • AI代理集成：设计用于与Claude、ChatGPT和其他AI助手配合使用
  • 搅拌机功能：保留所有搅拌机mcp功能，包括：
    • 场景操纵
    • 对象创建和编辑
    • 物料管理
    • PolyHaven资产整合
    • Hyper3D罗丹模型生成
  • 虚幻引擎功能:
    • 级别创建和管理
    • 资产导入
    • Python代码执行
    • 场景操纵
  • 延伸结构：轻松扩展Blender插件和服务器，同时保持与上游更新的兼容性

建筑

该系统由三个主要部分组成：

  1. MCP服务器：中央集线器通过端口8000上的SSE（服务器发送事件）与AI代理通信
  2. 搅拌机插件：Blender中端口8400（标准）或8401（扩展）上的套接字服务器
  3. 虚幻插件：虚幻引擎中端口8500上的HTTP服务器
[AI Agent] <--SSE--> [MCP Server (8300)] 
                        |
                        |--HTTP--> [Blender Addon (8400)]
                        |
                        |--HTTP--> [Unreal Plugin (8500)]

延伸结构

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

  • 搅拌机插件扩展：扩展原始 BlenderMCPServer 同时保持原始代码的完整性
  • 服务器扩展：通过附加工具和虚幻引擎集成增强原始服务器
  • 接口工具：提供用于安装、配置和运行扩展的实用程序

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

分步安装和设置指南

先决条件

  • Python 3.10或更高版本
  • Blender 3.0或更高版本
  • 虚幻引擎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：标准插件（原装搅拌机mcp）

  1. 打开搅拌机
  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. 打开搅拌机
  3. 导航到“编辑”>“首选项”>“附加组件”
  4. 查找并启用“接口：扩展搅拌机MCP”插件（选中复选框）

4.安装虚幻引擎插件

  1. 找到 UEPythonServer 此项目中的文件夹
  2. 将整个文件夹复制到虚幻项目的 Plugins 目录
    • 如果你的项目没有 Plugins 目录，创建一个
  3. 用你的项目启动虚幻引擎
  4. 导航到菜单中的编辑>插件
  5. 查找并启用Python服务器插件
  6. 出现提示时重新启动虚幻引擎

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. 在三维视口中，按 N 打开侧边栏面板
  3. 选择相应的选项卡：
    • “BlenderMCP”（如果使用标准插件）
    • “ExtBlenderMCP”（如果使用扩展插件）
  4. 点击“启动服务器”按钮
  5. 验证服务器是否成功启动（检查控制台输出）

7.验证虚幻引擎连接

  1. 运行虚幻引擎并启用插件
  2. Python服务器应该自动启动
  3. 检查输出日志（窗口>开发人员工具>输出日志）是否有任何消息
  4. 虚幻插件现在应该已经准备好接收命令了

8.连接AI代理

选项A：与Claude桌面版集成

将以下内容添加到Claude中以进行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：与游标集成

  1. 打开光标设置

  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代理与虚幻引擎交互，要求它：

    • 创建新关卡
    • 放置资产
    • 修改场景属性

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

故障排除

如果您遇到问题：

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

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

比较：标准与扩展

功能 标准服务器 扩展服务器
搅拌机控制 ✅ ✅
虚幻控制 ✅ ✅
自定义搅拌机命令 ❌ ✅
增强场景信息 ❌ ✅
自动特征检测 ❌ ✅
上游兼容性 ✅ ✅

为基本功能选择标准服务器，为高级功能选择扩展服务器。

发展

请参阅 项目文件 和 工作流 详细开发信息目录。

为了扩展此项目：

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

许可证

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

致谢

未来发展

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

结构化虚幻引擎API

目前，虚幻引擎的通信主要依赖于直接执行Python代码。计划中的增强是实现一个类似于Blender集成的结构化API：

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

这种增强将在两种发动机上创造更一致的体验，并提高系统的整体可靠性。请参阅 工作流文档 了解有关此计划开发的更多详细信息。

相关 MCP