尿素搅拌机-MCP

Unreal-Blender MCP

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

概述

该项目扩展了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 和 Unreal Engine
AI 代理集成：旨在与 Claude、ChatGPT 和其他 AI 助手配合使用
Blender 功能：保留所有 blender-mcp 功能，包括：
- 场景操控
- 对象创建和编辑
- 物料管理
- PolyHaven 资产整合
- Hyper3D Rodin 模型生成
虚幻引擎功能：
- 级别创建和管理
- 资源导入
- Python代码执行
- 场景操控
扩展结构：轻松扩展 Blender 插件和服务器，同时保持与上游更新的兼容性

建筑学

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

MCP 服务器：中央集线器通过端口 8000 上的 SSE（服务器发送事件）与 AI 代理进行通信
Blender 插件：Blender 内的套接字服务器，端口为 8400（标准）或 8401（扩展）
虚幻插件：虚幻引擎内的 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）

打开 Blender
导航至“编辑”>“首选项”>“附加组件”
点击“安装...”按钮
浏览并选择blender-mcp/addon.py文件
启用“界面：Blender MCP”插件（勾选该框）

选项 B：扩展插件（具有附加功能）

运行扩展安装程序脚本：
python -c "from src.unreal_blender_mcp.blender_addon import BlenderAddonManager; BlenderAddonManager().install_to_blender(force=True)"
打开 Blender
导航至“编辑”>“首选项”>“附加组件”
找到并启用“界面：扩展 Blender MCP”插件（勾选该框）

4.安装虚幻引擎插件

找到此项目中的UEPythonServer文件夹
将整个文件夹复制到虚幻项目的Plugins目录
- 如果您的项目没有Plugins目录，请创建一个
使用你的项目启动虚幻引擎
在菜单中导航至“编辑”>“插件”
查找并启用 Python 服务器插件
出现提示时重新启动虚幻引擎

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服务器连接

启动 Blender（如果尚未运行）
在 3D 视口中，按N打开侧边栏面板
选择适当的选项卡：
- “BlenderMCP”（如果使用标准插件）
- “ExtBlenderMCP”（如果使用扩展插件）
点击“启动服务器”按钮
验证服务器是否启动成功（检查控制台输出）

7.验证虚幻引擎连接

运行虚幻引擎并启用插件
Python 服务器应该自动启动
检查输出日志（窗口 > 开发者工具 > 输出日志）中是否有任何消息
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 集成

打开游标设置
导航至 MCP 部分
添加以下命令：
- 标准服务器： 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. 测试系统

一旦所有组件都运行：

使用您的 AI 代理与 Blender 进行交互，要求它执行以下操作：
- 创建一个简单的立方体或球体
- 修改对象属性
- 创建材质
使用您的 AI 代理与虚幻引擎进行交互，方法是：
- 创建新级别
- 放置资产
- 修改场景属性
尝试需要两个平台协同工作的更复杂的操作

故障排除

如果您遇到问题：

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

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

比较：标准版与扩展版

特征	标准服务器	扩展服务器
搅拌机控制	✅	✅
虚幻控制	✅	✅
自定义 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为基础。

未来发展

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

结构化虚幻引擎 API

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

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

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

This server cannot be installed

security - not tested

license - not found

quality - not tested

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.