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]  [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)"

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

4.安装虚幻引擎插件

1. 找到 UEPythonServer 此项目中的文件夹
2. 将整个文件夹复制到虚幻项目的 Plugins 目录

- 如果你的项目没有 Plugins 目录，创建一个

1. 用你的项目启动虚幻引擎
2. 导航到菜单中的编辑>插件
3. 查找并启用Python服务器插件
4. 出现提示时重新启动虚幻引擎

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”（如果使用扩展插件）

1. 点击“启动服务器”按钮
2. 验证服务器是否成功启动（检查控制台输出）

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. 打开光标设置

1. 导航到MCP部分

1. 添加以下命令：

- 标准服务器： 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交互，要求它：

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

1. 使用您的AI代理与虚幻引擎交互，要求它：

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

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

故障排除

如果您遇到问题：

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许可证获得许可-有关详细信息，请参阅许可证文件。

致谢

• 该项目建立在 搅拌机mcp 悉达多Ahuja。

未来发展

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

结构化虚幻引擎API

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

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

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