Unreal-Blender MCP

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

概述

该项目扩展了blender-mcp框架以包含对虚幻引擎的支持，允许 Claude 和 ChatGPT 等 AI 代理通过单一界面同时控制两个平台。

Related MCP server: soft-ue-cli

子模块信息

本项目包含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 模型生成

• 虚幻引擎功能：

  • 级别创建和管理

  • 资源导入

  • Python代码执行

  • 场景操控

• 扩展结构：轻松扩展 Blender 插件和服务器，同时保持与上游更新的兼容性

建筑学

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

1. MCP 服务器：中央集线器通过端口 8000 上的 SSE（服务器发送事件）与 AI 代理进行通信

2. Blender 插件：Blender 内的套接字服务器，端口为 8400（标准）或 8401（扩展）

3. 虚幻插件：虚幻引擎内的 HTTP 服务器，端口 8500

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

扩展结构

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

• Blender Addon Extension ：扩展原始的BlenderMCPServer ，同时保持原始代码不变

• 服务器扩展：通过附加工具和虚幻引擎集成增强原始服务器

• 界面工具：提供安装、配置和运行扩展的实用程序

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

分步安装和设置指南

先决条件

• 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. 启用“界面：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.安装虚幻引擎插件

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. 在 3D 视口中，按N打开侧边栏面板

3. 选择适当的选项卡：

   • “BlenderMCP”（如果使用标准插件）

   • “ExtBlenderMCP”（如果使用扩展插件）

4. 点击“启动服务器”按钮

5. 验证服务器是否启动成功（检查控制台输出）

7.验证虚幻引擎连接

1. 运行虚幻引擎并启用插件

2. Python 服务器应该自动启动

3. 检查输出日志（窗口 > 开发者工具 > 输出日志）中是否有任何消息

4. Unreal 插件现在应该可以接收命令了

8. 连接AI代理

选项 A：与 Claude 桌面版集成

将以下内容添加到 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. 打开游标设置

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、Unreal）

2. 验证端口配置是否匹配（默认值：MCP 为 8000，Blender 为 8400/8401，Unreal 为 8500）

3. 检查控制台输出中的错误消息

4. 按正确的顺序重新启动组件：首先是 MCP 服务器，然后是 Blender，然后是 Unreal Engine

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

比较：标准版与扩展版

选择标准服务器以实现基本功能或选择扩展服务器以实现高级功能。

发展

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

为了扩展此项目：

• 要添加新的 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为基础。

未来发展

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

结构化虚幻引擎 API

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

• 为常见的虚幻引擎操作创建预定义函数

• 实施适当的错误处理和验证

• 通过限制执行范围来提高安全性

• 增强运营的稳定性和可预测性

• 添加结构时保持向后兼容性

此项增强功能将在两个引擎之间创造更一致的体验，并提高系统的整体可靠性。有关此计划开发的详细信息，请参阅工作流程文档。