AI导哈

Blender MCP综合服务器

一个生产就绪的模型上下文协议（MCP）服务器，提供全面的Blender集成，覆盖从场景管理到最终渲染的完整3D创作流程。

  • by Pervaiz106
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 Pervaiz106/Blender-Mcp-Server

使用说明

Blender MCP综合服务器

一个生产就绪的模型上下文协议（MCP）服务器，提供全面的Blender集成 47+工具 涵盖了从场景管理到最终渲染的完整3D创建工作流程。

🌟 概述

这个全面的MCP服务器使AI系统能够通过安全、有据可查的界面以编程方式与Blender的3D创建功能进行交互。它通过用于3D建模、动画和渲染的不同方面的分类工具，提供对Blender的Python API（bpy）的完整访问。

🚀 特性

综合工具集（47+工具）

🎬 场景管理（8个工具）

  • create_scene -创建新的Blender场景
  • set_scene_properties -配置帧范围和单位
  • get_scene_info -获取详细的场景信息
  • duplicate_scene -克隆现有场景
  • delete_scene -删除场景（确认后）
  • set_world_properties -配置世界/环境设置
  • get_world_properties -获取当前世界设置
  • clear_scene -删除所有对象（确认后）

📦 对象操作（9个工具）

  • create_object -创建几何图元和对象
  • transform_object -移动、旋转和缩放对象
  • delete_object -删除对象（确认后）
  • duplicate_object -克隆对象
  • join_objects -组合多个对象
  • separate_objects -分割网格对象
  • parent_object -建立亲子关系
  • unparent_object -删除父关系
  • get_object_info -获取详细的对象信息

🎨 物料管理（7个工具）

  • create_material -创建具有自定义特性的PBR材质
  • assign_material -将材质应用于对象
  • update_material_properties -修改材质设置
  • delete_material -移除材料（确认后）
  • duplicate_material -克隆材料
  • get_material_info -获取材料详细信息
  • list_materials -列出所有场景材质

🔧 网格操作（6个工具）

  • edit_mesh -执行网格编辑操作（细分、斜面等）
  • apply_modifier -将修改器应用于对象
  • add_modifier -添加修饰符而不应用
  • remove_modifier -删除修饰符（确认后）
  • get_mesh_info -获取详细的网格数据（顶点、面等）
  • remesh_object -应用重网格算法

🎬 动画系统（6个工具）

  • create_animation -使用关键帧创建复杂的动画
  • set_keyframes -设置单个变换关键帧
  • play_animation -开始播放动画
  • stop_animation -停止动画播放
  • clear_animation -删除动画数据（确认后）
  • get_animation_info -获取动画详细信息

🎨 渲染管道（5个工具）

  • render_scene -渲染当前场景
  • set_render_settings -配置渲染引擎和质量
  • get_render_settings -获取当前渲染配置
  • preview_render -创建快速预览渲染
  • get_render_preview -以图像形式获取渲染预览

📁 文件I/O操作（4个工具）

  • import_file -导入三维模型（OBJ、FBX、GLTF、STL等）
  • export_file -将对象导出为各种格式
  • save_scene -保存.blend文件
  • load_scene -加载.blend文件（确认）

📷 相机和照明（4个工具）

  • create_camera -使用自定义设置创建相机
  • set_active_camera -设置活动摄影机进行渲染
  • setup_lighting -应用预定义的照明设置
  • create_light -创建单个灯光（日光、聚光灯、点、面积）

🔧 实用工具（附加）

  • get_viewport_screenshot -捕获视口屏幕截图
  • execute_blender_code -在Blender中执行自定义Python代码
  • get_server_status -获取服务器和连接状态

🏗️ 建筑

核心组件

  1. FastMCP服务器 -基于FastMCP 2.0框架构建，用于生产就绪的MCP实施
  2. 搅拌机连接 -基于Socket的Blender插件通信
  3. 工具类别 -为不同的3D工作流程阶段组织工具集
  4. 错误处理 -三层模型的稳健错误处理
  5. 安全 -破坏性操作的输入验证和确认机制

技术栈

  • FastMCP 2.0 -高性能MCP框架
  • Python 3.10+ -带有类型提示的现代Python
  • 派丹蒂克 -数据验证和序列化
  • 套接字通信 -实时Blender集成
  • Blender Python API（bpy） -直接访问Blender功能

📦 安装

先决条件

  1. 搅拌机3.0+ 安装了MCP插件
  2. Python 3.10+
  3. uv包管理器

快速开始

  1. 克隆或下载项目：
# The server is ready to run from the project directory
cd blender-mcp-comprehensive
  1. 安装依赖项：
# Dependencies will be installed automatically on first run
# or manually with:
uv sync

  1. 使用MCP插件启动Blender：

    • 打开搅拌机
    • 安装并启用Blender MCP插件
    • 在插件面板中单击“连接到Claude”

  2. 运行MCP服务器：

# Using the startup script
sh run.sh

# Or directly with uv
uv run python -m src.blender_mcp_server.server

🔧 配置

环境变量

可以使用环境变量配置服务器：

# Blender connection settings
export BLENDER_HOST="localhost"      # Default: localhost
export BLENDER_PORT="9876"           # Default: 9876

MCP客户端配置

对于Claude Desktop集成，请添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "blender-comprehensive": {
      "command": "sh",
      "args": ["/path/to/blender-mcp-comprehensive/run.sh"]
    }
  }
}

🚀 用法

基本使用示例

创建简单场景

# Create a new scene
await client.call_tool("create_scene", {"name": "My Scene"})

# Add some objects
await client.call_tool("create_object", {
    "object_type": "CUBE",
    "name": "Building",
    "location": [0, 0, 0]
})

await client.call_tool("create_object", {
    "object_type": "SPHERE",
    "name": "Planet",
    "location": [5, 0, 2]
})

# Create and assign materials
await client.call_tool("create_material", {
    "name": "Brick",
    "base_color": [0.8, 0.3, 0.2],
    "roughness": 0.8
})

await client.call_tool("assign_material", {
    "object_name": "Building",
    "material_name": "Brick"
})

创建动画

# Create orbital animation
keyframes = [
    {"frame": 1, "location": [5, 0, 2], "interpolation": "BEZIER"},
    {"frame": 100, "location": [0, 5, 2], "interpolation": "BEZIER"},
    {"frame": 200, "location": [-5, 0, 2], "interpolation": "BEZIER"},
    {"frame": 300, "location": [0, -5, 2], "interpolation": "BEZIER"},
    {"frame": 400, "location": [5, 0, 2], "interpolation": "BEZIER"}
]

await client.call_tool("create_animation", {
    "object_name": "Planet",
    "animation_type": "LOCATION",
    "keyframes": keyframes
})

渲染场景

# Configure render settings
await client.call_tool("set_render_settings", {
    "settings": {
        "engine": "CYCLES",
        "resolution_x": 1920,
        "resolution_y": 1080,
        "samples": 128
    }
})

# Create preview render
await client.call_tool("preview_render", {"resolution": 800})

高级用法

请参阅中的综合示例 /examples/usage_examples.py 这表明：

  • 从场景创建到最终渲染的完整工作流程
  • 高级材料创建和分配
  • 复杂的网格操作和修改器
  • 复杂的动画系统
  • 文件I/O操作
  • 摄像头和照明设置

🧪 测试

服务器包括全面的测试覆盖：

运行验证测试

# Run all tests
cd blender-mcp-comprehensive
python -m pytest tests/ -v

# Run specific test categories
python -m pytest tests/test_blender_mcp_server.py::TestBlenderMCPServer::test_scene_management_tools -v
python -m pytest tests/test_blender_mcp_server.py::TestBlenderMCPServer::test_object_operations_tools -v

测试类别

  • 工具验证 -确保所有47+工具都正确暴露
  • 参数验证 -测试参数处理和错误案例
  • 连接测试 -验证Blender连接
  • 集成测试 -测试完整的工作流程场景
  • 错误处理 -测试故障模式和恢复

🔒 安全

安全特性

  1. 确认要求 -破坏性操作需要明确确认
  2. 输入验证 -所有参数在处理前都经过验证
  3. 误差边界 -全面的错误处理可防止崩溃
  4. 沙盒执行 -操作在受控环境中运行
  5. 连接验证 -操作前验证Blender连接

安全操作示例

# Destructive operations require confirmation
await client.call_tool("delete_object", {
    "object_name": "ImportantObject",
    "confirm": True  # Required for deletion
})

await client.call_tool("clear_scene", {
    "confirm": True  # Required for clearing entire scene
})

🔧 故障排除

常见问题

连接问题

Error: "Failed to connect to Blender"

解决方案： 确保Blender在启用MCP插件的情况下运行，并单击“连接到Claude”。

超时错误

Error: "Timeout waiting for Blender response"

解决方案：

  • 通过将复杂的操作分解为更小的步骤来简化请求
  • 检查搅拌机的响应性
  • 验证网络连接

权限错误

Error: "Permission denied" during file operations

解决方案：

  • 检查文件路径和权限
  • 确保输出目录存在
  • 使用适当的用户权限运行

调试模式

启用详细日志记录：

export BLENDER_MCP_DEBUG=1
sh run.sh

📚 API 参考

工具类别

场景管理

  • create_scene（名称） -创建新场景
  • set_scene_properties（frame_start、frame_end、frame_current、单位） -配置场景
  • get_scene_info（） -获取场景信息
  • 复制场景（源名、新名） -克隆场景
  • delete_scene（scene_name，confirm=True） -删除场景
  • set_world_properties（颜色、背景类型） -配置环境
  • 获取世界属性（） -获取世界设置
  • clear_scene（确认=真） -清除所有对象

对象操作

  • create_object（对象类型、名称、位置） -创建对象
  • transform_object（对象名、位置、旋转、比例） -变换对象
  • delete_object（对象名，确认=真） -删除对象
  • 复制对象（源名、新名） -克隆对象
  • join_objects（对象名称，joined_name） -组合对象
  • separate_objects（对象名，模式） -拆分对象
  • parent_object（child_name、parent_name、keep_transform） -设置层次结构
  • unpant_object（child_name，keep_transform） -删除层次结构
  • get_object_info（对象名） -获取对象详细信息

[源代码中提供了其他工具文档]

🤝 贡献

开发环境设置

  1. 克隆存储库
  2. 安装开发依赖项：
uv sync --dev
  1. 运行测试：
python -m pytest tests/ -v
  1. 代码格式：
black src/ tests/
ruff check src/ tests/

添加新工具

  1. 添加工具功能 @mcp.tool 装饰器
  2. 包含带参数的综合文档字符串
  3. 添加参数验证和错误处理
  4. 为新工具编写测试
  5. 更新文档

代码的风格

  • 遵循PEP 8风格指南
  • 对所有参数和返回值使用类型提示
  • 包含全面的文档字符串
  • 编写新功能的单元测试
  • 保持向后兼容性

📄 许可证

MIT许可证-有关详细信息，请参阅许可证文件。

🙏 致谢

  • FastMCP团队 -对于优秀的MCP框架
  • Blender基金会 -用于强大的3D创建套件
  • MCP社区 -用于协议标准化
  • Python生态系统 -用于强大的开发工具

📞 支持

  • 文档： 包括全面的示例和API参考资料
  • 测试： 用于验证的完整测试套件
  • 问题： 通过GitHub问题报告错误和功能请求
  • 社区： 加入MCP社区频道的讨论

内置❤️ MiniMax代理

通过全面的Blender集成实现AI驱动的3D创建。

相关 MCP