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

BlenderMCP 通过模型上下文协议 (MCP) 将 Blender 与 Claude AI 连接起来，使 Claude 能够直接与 Blender 交互并控制它。这种集成实现了提示词辅助的 3D 建模、场景创建和操作。

我们没有官方网站。您在网上看到的任何网站都是非官方的，与本项目没有任何关联。请自行承担使用风险。

完整教程

加入社区

提供反馈、获取灵感，并基于 MCP 进行开发：Discord

支持者

CodeRabbit

所有支持者：

支持本项目

当前版本(1.5.5)

• 添加了 Hunyuan3D 支持
• 查看 Blender 视口截图，以便更好地理解场景
• 搜索并下载 Sketchfab 模型
• 通过 Poly Haven 的 API 支持其资源
• 支持使用 Hyper3D Rodin 生成 3D 模型
• 在远程主机上运行 Blender MCP
• 对执行的工具进行遥测（完全匿名）

安装新版本（现有用户）

• 对于新用户，可以直接前往安装部分。对于现有用户，请参阅以下说明。
• 下载最新的 addon.py 文件并替换旧文件，然后将其添加到 Blender 中。
• 从 Claude 中删除 MCP 服务器并重新添加，这样应该就可以正常使用了！

功能

• 双向通信：通过基于套接字的服务器将 Claude AI 连接到 Blender
• 对象操作：在 Blender 中创建、修改和删除 3D 对象
• 材质控制：应用和修改材质与颜色
• 场景检查：获取当前 Blender 场景的详细信息
• 代码执行：从 Claude 在 Blender 中运行任意 Python 代码

组件

该系统由两个主要组件组成：

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

安装

先决条件

• Blender 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）

示例：

export BLENDER_HOST='host.docker.internal'
export BLENDER_PORT=9876

Claude for Desktop 集成

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

转到 Claude > 设置 > 开发人员 > 编辑配置 > claude_desktop_config.json，加入以下内容：

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

claude mcp add blender uvx blender-mcp

Cursor 集成

对于 Mac 用户，前往设置 > MCP 并粘贴以下内容：

• 若要作为全局服务器使用，请使用“添加新的全局 MCP 服务器”按钮并粘贴
• 若要作为项目特定服务器使用，请在项目的根目录下创建 .cursor/mcp.json 文件并粘贴

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

对于 Windows 用户，前往设置 > MCP > 添加服务器，添加一台具有以下设置的新服务器：

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

Cursor 设置视频

⚠️ 请仅运行一个 MCP 服务器实例（无论是 Cursor 还是 Claude Desktop），不要同时运行两者

Visual Studio Code 集成

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

安装 Blender 插件

1. 从本仓库下载 addon.py 文件
2. 打开 Blender
3. 转到 编辑 > 首选项 > 插件
4. 点击“安装...”并选择 addon.py 文件
5. 通过勾选“界面：Blender MCP”旁边的复选框启用插件

使用方法

启动连接

1. 在 Blender 中，打开 3D 视图侧边栏（如果未显示，请按 N 键）
2. 找到“BlenderMCP”选项卡
3. 如果需要来自 Poly Haven API 的资源，请勾选 Poly Haven 复选框（可选）
4. 点击“连接到 Claude”
5. 确保 MCP 服务器正在您的终端中运行

与 Claude 一起使用

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

功能

• 获取场景和对象信息
• 创建、删除和修改形状
• 应用或创建对象的材质
• 在 Blender 中执行任何 Python 代码
• 通过 Poly Haven 下载合适的模型、资源和 HDRIs
• 通过 Hyper3D Rodin 生成 AI 3D 模型

示例命令

以下是一些你可以让 Claude 做的事情示例：

• “创建一个地牢中的低多边形场景，有一条龙守护着一罐金子” 演示
• “使用 HDRI、纹理以及来自 Poly Haven 的岩石和植被模型，创建海滩氛围” 演示
• 提供一张参考图，并据此创建一个 Blender 场景 演示
• “通过 Hyper3D 生成一个花园小矮人的 3D 模型”
• “获取当前场景的信息，并基于此制作一个 Three.js 草图” 演示
• “把这辆车变成红色金属质感”
• “创建一个球体，并将其放置在立方体上方”
• “将灯光设置为影棚风格”
• “将相机对准场景，并使其变为等轴测视图”

Hyper3D 集成

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

故障排除

• 连接问题：确保 Blender 插件服务器正在运行，并且 MCP 服务器已在 Claude 中正确配置。请勿在终端中运行 uvx 命令。有时，第一条命令可能无法成功，但之后就会正常工作。
• 超时错误：尝试简化你的请求，或将它们分解为更小的步骤。
• Poly Haven 集成：Claude 在处理 Poly Haven 时有时表现不稳定。
• 你试过关机再开机吗？：如果仍然遇到连接问题，请尝试重启 Claude 和 Blender 服务器。

技术细节

通信协议

系统使用基于 JSON 的简单协议，通过 TCP 套接字进行通信：

• 命令以 JSON 对象形式发送，包含 type 和可选的 params 字段。
• 响应也是 JSON 对象，包含 status、result 或 message 字段。

局限性与安全考虑

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

遥测控制

BlenderMCP 会收集匿名的使用数据，以帮助改进工具。你可以通过两种方式控制遥测：

1. 在 Blender 中：前往 编辑 > 首选项 > 插件 > Blender MCP，取消勾选遥测同意复选框。

   • 如果同意（已勾选）：收集匿名化的提示、代码片段和截图。
   • 如果不同意（未勾选）：仅收集最少的匿名使用数据（工具名称、成功/失败状态、持续时间）。

2. 环境变量：完全禁用所有遥测，只需运行：

DISABLE_TELEMETRY=true uvx blender-mcp

或者将其添加到你的 MCP 配置中：

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

所有遥测数据均完全匿名化，仅用于改进 BlenderMCP。

贡献

欢迎贡献！请随时提交 Pull Request。

免责声明

这是一个第三方集成，并非由 Blender 官方开发。由 Siddharth 制作。

BlenderMCP 快速上手指南

BlenderMCP 通过模型上下文协议（MCP）将 Blender 与 Claude AI 连接，使您能够通过自然语言提示直接控制 Blender 进行 3D 建模、场景创建和操作。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：Windows, macOS 或 Linux
• Blender：版本 3.0 或更高
• Python：版本 3.10 或更高
• 包管理器：必须安装 uv

安装 uv 包管理器

macOS 用户：

brew install uv

Windows 用户： 在 PowerShell 中运行以下命令安装，并将 uv 添加到用户环境变量路径中（安装后可能需要重启 Claude Desktop）：

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

添加环境变量：

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

⚠️ 注意：未安装 uv 前请勿继续后续步骤。

安装步骤

本工具由两部分组成：Blender 插件和 MCP 服务器。请依次完成以下安装。

1. 安装 Blender 插件

1. 从项目仓库下载 addon.py 文件。
2. 打开 Blender，进入 Edit > Preferences > Add-ons。
3. 点击 Install... 按钮，选择下载的 addon.py 文件。
4. 勾选 Interface: Blender MCP 以启用插件。

2. 配置 MCP 服务器

根据您的开发工具选择以下一种方式进行配置：

方案 A：Claude Desktop

编辑配置文件 claude_desktop_config.json (路径：Claude > Settings > Developer > Edit Config)，加入以下内容：

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

或者使用 Claude Code CLI：

claude mcp add blender uvx blender-mcp

方案 B：Cursor IDE

• Mac 用户：进入 Settings > MCP，点击 "add new global MCP server" 或创建项目根目录下的 .cursor/mcp.json，粘贴以下配置：

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

• Windows 用户：进入 Settings > MCP > Add Server，添加新服务器并填入：

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

⚠️ 重要：请勿同时在 Cursor 和 Claude Desktop 中运行 MCP 服务器实例，只需选择其一。

方案 C：Visual Studio Code

点击以下按钮直接在 VS Code 中安装：

基本使用

1. 启动连接

1. 打开 Blender，按 N 键展开右侧侧边栏。
2. 找到 BlenderMCP 标签页。
3. （可选）如果需要访问 Poly Haven 资源库，勾选相应复选框。
4. 点击 Connect to Claude 按钮。
5. 确保您的 AI 编辑器（Claude/Cursor/VS Code）已加载配置并准备就绪。

2. 开始交互

配置完成后，您在 AI 聊天窗口中将看到带有锤子图标的 Blender 工具集。现在可以直接通过自然语言下达指令。

使用示例：

• 创建基础几何体：

  "Create a sphere and place it above the cube" （创建一个球体并将其放置在立方体上方）

• 修改材质与颜色：

  "Make this car red and metallic" （将这辆车改为红色金属材质）

• 构建复杂场景：

  "Create a low poly scene in a dungeon, with a dragon guarding a pot of gold" （创建一个低多边形风格的地牢场景，里面有一条龙守护着一罐金币）

• 调用外部资源：

  "Create a beach vibe using HDRIs, textures, and models like rocks and vegetation from Poly Haven" （使用 Poly Haven 的 HDRI、纹理以及岩石和植被模型创建一个海滩氛围场景）

• 生成 AI 3D 模型 (需 Hyper3D Key)：

  "Generate a 3D model of a garden gnome through Hyper3D" （通过 Hyper3D 生成一个花园侏儒的 3D 模型）

• 执行自定义代码：

  "Get information about the current scene, and make a threejs sketch from it" （获取当前场景信息并据此生成一个 Three.js 草图）

隐私与遥测控制

默认情况下，工具会收集匿名使用数据以改进产品。若您希望禁用：

• 在 Blender 中：进入 Edit > Preferences > Add-ons > Blender MCP，取消勾选遥测同意选项。
• 通过环境变量：在启动命令中添加 DISABLE_TELEMETRY=true，或在 MCP 配置中加入：

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