AI导哈

Blender AI集成工具

BlenderMCP通过模型上下文协议（MCP）将Blender与Claude AI连接，实现AI辅助3D建模与场景控制。

  • by IAmMarcellus
  • Python
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 IAmMarcellus/BlenderMCP

使用说明

BlenderMCP-Blender模型上下文协议集成

BlenderMCP通过模型上下文协议（MCP）将Blender连接到Claude AI，允许Claude直接与Blender交互和控制Blender。这种集成实现了快速辅助的3D建模、场景创建和操纵。

我们没有官方网站。你在网上看到的任何网站都是非官方的，与这个项目没有任何关系。使用它们的风险由你自己承担。

完整教程

加入社区

提供反馈，获得灵感，并在MCP的基础上进行构建： 不和

支持者

代码兔

萨蒂什·戈达

所有支持者：

支持这个项目

发行说明（1.4.0）

  • 新增Hunyuan3D支持

以前添加的功能：

  • 查看Blender视口的屏幕截图，以更好地理解场景
  • 搜索并下载Sketchfab模型
  • 通过其API支持保利港资产
  • 支持使用Hyper3D Rodin生成3D模型
  • 在远程主机上运行Blender MCP
  • 执行工具的遥测（完全匿名）

安装新版本（现有用户）

  • 对于新手，您可以直接进入安装。对于现有用户，请参阅以下要点
  • 下载最新的addon.py文件并替换旧文件，然后将其添加到Blender中
  • 从Claude中删除MCP服务器并重新添加，您应该可以使用了！

特性

  • 双向通信：通过基于套接字的服务器将Claude AI连接到Blender
  • 一流的工具：常见的Blender操作以类型化MCP工具的形式公开（不仅仅是Python执行）
  • DSL兼容：通过以下方式执行已验证的已分配操作列表 execute_ops （比任意Python更安全）
  • 对象操作：在Blender中创建、修改和删除3D对象
  • 材料控制：创建/指定材质、设置PBR参数和线纹理贴图
  • 现场检查：获取当前Blender场景的详细信息
  • 代码执行：从Claude在Blender中运行任意Python代码

组件

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

  1. 搅拌机插件(addon.py)：Blender插件，在Blender中创建套接字服务器以接收和执行命令
  2. MCP服务器(src/blender_mcp/server.py)：实现模型上下文协议并连接到Blender插件的Python服务器

安装

先决条件

  • 搅拌机3.0或更新版本
  • Python 3.10或更新版本
  • uv包管理器：

如果您使用的是Mac，请将uv安装为

brew install uv

在Windows上

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

然后将uv添加到Windows中的用户路径中（之后可能需要重新启动Claude Desktop）：

$localBin = "$env:USERPROFILE\.local\bin"
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$userPath;$localBin", "User")

否则，安装说明在他们的网站上： 安装uv

⚠️ 安装UV之前不要继续

环境变量

以下环境变量可用于配置Blender连接：

  • BLENDER_HOST：Blender套接字服务器的主机地址（默认：“localhost”）
  • BLENDER_PORT：Blender套接字服务器的端口号（默认值：9876）
  • BLENDER_AUTH_TOKEN：可选共享密钥。如果在Blender（插件首选项）中设置，MCP服务器必须发送相同的令牌。
  • BLENDER_MCP_TOOL_PROFILE：控制暴露的MCP工具数量（默认值： "standard").

工具配置文件：

  • minimal：仅公开 get_scene_info, get_viewport_screenshot, get_capabilities, execute_ops
  • standard （默认）： minimal +普通包装纸(create_primitive, set_transform, select_objects, assign_material, render_still)
    • 只有当Blender插件报告在服务器启动时启用了集成工具（PolyHaven/Sketchfab/Hyper3D/Hunyuan）时，才会注册这些工具（需要重新启动以重新评估）。
  • full：显示所有工具（包括高级包装器和 execute_blender_code 逃生舱）

例子：

export BLENDER_HOST='host.docker.internal'
export BLENDER_PORT=9876
export BLENDER_AUTH_TOKEN='...'
export BLENDER_MCP_TOOL_PROFILE='standard'

Claude桌面集成

观看设置说明视频 （假设您已经安装了uv）

转到Claude>设置>开发人员>编辑配置>Claude_desktop_Config.json，以包含以下内容：

{
    "mcpServers": {
        "blender": {
            "command": "uvx",
            "args": [
                "blender-mcp"
            ]
        }
    }
}

光标集成

对于Mac用户，请转到“设置”>“MCP”并粘贴以下内容

  • 要用作全局服务器，请使用“添加新的全局MCP服务器”按钮并粘贴
  • 要用作特定于项目的服务器，请创建 .cursor/mcp.json 在项目的根和粘贴
{
    "mcpServers": {
        "blender": {
            "command": "uvx",
            "args": [
                "blender-mcp"
            ]
        }
    }
}

对于Windows用户，请转到“设置”>“MCP”>“添加服务器”，使用以下设置添加新服务器：

{
    "mcpServers": {
        "blender": {
            "command": "cmd",
            "args": [
                "/c",
                "uvx",
                "blender-mcp"
            ]
        }
    }
}

光标设置视频

⚠️ 只运行一个MCP服务器实例（在Cursor或Claude Desktop上），而不是两者都运行

Visual Studio代码集成

先决条件：确保你有 Visual Studio Code 在继续之前安装。

安装Blender插件

  1. 下载 addon.py 此仓库中的文件
  2. 打开搅拌机
  3. 转到“编辑”>“首选项”>“附加组件”
  4. 点击“安装…”并选择 addon.py 文件
  5. 通过选中“接口：Blender MCP”旁边的框启用插件

用法

启动连接

  1. 在Blender中，转到3D视图侧栏（如果不可见，请按N）
  2. 找到“BlenderMCP”选项卡
  3. 如果您希望资产来自其API，请启用Poly Haven复选框（可选）
  4. 点击“连接到克劳德”
  5. 确保MCP服务器正在您的终端中运行

与克劳德一起使用

一旦在Claude上设置了配置文件，并且插件在Blender上运行，您将看到一个带有Blender MCP工具的锤子图标。

能力

  • 获取场景和对象信息
  • 创建、删除和修改形状
  • 为对象应用或创建材质
  • 在Blender中执行任何Python代码
  • 通过下载正确的型号、资产和HDRI 聚天堂
  • 通过AI生成3D模型 Hyper3D罗丹
  • 通过DSL执行分配的操作(execute_ops)实现更安全、更有条理的场景切换

新增：DSL+工具表面（v1）

  • 能力发现: get_capabilities() 返回DSL版本、支持的操作、格式和启用的集成。
  • DSL执行: execute_ops({dsl_version, transaction, dry_run, ops:[...]})
    • transaction: "atomic" （默认）尝试使用Blender undo回滚错误； "none" 尽最大努力。
    • dry_run：验证并返回规范化的请求，而不执行。

示例（创建立方体、制作材质、指定材质）：

{
  "dsl_version": "1",
  "transaction": "atomic",
  "dry_run": false,
  "ops": [
    {"type": "create_primitive", "primitive": "cube", "name": "Cube_A", "size": 2.0, "location": [0, 0, 1]},
    {"type": "ensure_material", "name": "RedPaint", "model": "pbr"},
    {"type": "set_material_params", "material": "RedPaint", "params": {"baseColor": [1, 0, 0, 1], "roughness": 0.4}},
    {"type": "assign_material", "object": "Cube_A", "material": "RedPaint", "slot": 0}
  ]
}

示例（添加并应用斜面修改器）：

{
  "dsl_version": "1",
  "transaction": "atomic",
  "ops": [
    {"type": "add_modifier", "name": "Cube_A", "modifier_type": "bevel", "params": {"width": 0.02, "segments": 3}},
    {"type": "apply_modifier", "name": "Cube_A", "modifier_name": "BEVEL"}
  ]
}

工具列表（v1）

核心：

  • get_scene_info, get_object_info, get_viewport_screenshot
  • list_objects, get_selection, select_objects
  • get_world_info, get_collections
  • get_capabilities

对象/变换：

  • create_primitive, delete_objects, duplicate_objects, rename_object
  • set_transform, apply_transform, snap_to_ground, set_origin
  • set_shading, recalculate_normals, merge_by_distance, triangulate
  • join_objects, separate_mesh, convert_to_mesh
  • set_visibility, set_collection_visibility, isolate_objects
  • ensure_collection, move_to_collection, set_parent, clear_parent

材料：

  • list_materials, create_material, set_material_params, assign_material, set_texture_maps

修改器：

  • list_modifiers, add_modifier, apply_modifier, remove_modifier

紫外线/烘烤：

  • uv_smart_project, uv_unwrap, uv_pack_islands
  • bake_maps

相机/灯光/世界：

  • create_camera, set_camera_params, set_active_camera, frame_camera_on_objects
  • camera_look_at, create_turntable_animation
  • create_light, set_light_params
  • set_world_background, set_world_hdri

进口/出口：

  • import_model, export_scene

致使：

  • set_render_settings, render_still, render_animation

项目卫生：

  • purge_orphans, pack_external_data, save_blend

示例命令

以下是一些你可以要求克劳德做的事情的例子：

  • “在地牢中创建一个低多边形场景，龙守卫着一罐金子” 演示
  • “使用HDRI、纹理和Poly Haven的岩石和植被等模型营造海滩氛围” 演示
  • 给出一个参考图像，并从中创建一个Blender场景 演示
  • “通过Hyper3D生成花园侏儒的3D模型”
  • 获取当前场景的信息，并从中绘制threejs草图 演示
  • “让这辆车变成红色和金属色”
  • “创建一个球体并将其放置在立方体上方”
  • “让灯光像工作室一样”
  • 将相机对准场景，并使其等距

Hyper3D集成

Hyper3D的免费试用密钥允许您每天生成有限数量的模型。如果达到每日限制，您可以等待第二天的重置，或从hyper3d.ai和fal.ai获取自己的密钥。

故障排除

  • 连接问题：确保Blender插件服务器正在运行，并且MCP服务器已在Claude上配置，不要在终端中运行uvx命令。有时，第一个命令不会执行，但之后它就开始工作了。
  • 超时错误：尝试简化您的请求或将其分解为更小的步骤
  • Poly-Haven整合克劳德有时行为古怪
  • 你试过把它关掉再打开吗？：如果您仍然存在连接错误，请尝试重新启动Claude和Blender服务器

技术细节

通信协议

该系统在TCP套接字上使用简单的基于JSON的协议：

  • 命令 以JSON对象的形式发送 type 可选 params
  • 回复 JSON对象具有 status 和 result 或 message

限制和安全考虑

  • 这 execute_blender_code 该工具允许在Blender中运行任意Python代码，这可能很强大，但有潜在的危险。在生产环境中小心使用。在使用之前，一定要保存好你的工作。
  • Poly Haven需要下载模型、纹理和HDRI图像。如果您不想使用它，请在Blender中的复选框中将其关闭。
  • 复杂的操作可能需要分解为更小的步骤

贡献

欢迎投稿！请随时提交拉取请求。

免责声明

这是一个第三方集成，不是由Blender制作的。由...制作 悉达多

相关 MCP