项目文件夹

Blender 插件（addon.py）：在 Blender 内创建 socket 服务器以接收并执行命令的 Blender 插件
MCP 服务器（src/blender_mcp/server.py）：实现 Model Context Protocol 并连接到 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"

然后在 Windows 中将 uv 添加到用户 PATH（之后可能需要重启 Claude Desktop）：

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

其他安装说明请参见其官网：Install uv

Linux： 使用 curl -LsSf https://astral.sh/uv/install.sh | sh 安装 uv（会安装到 ~/.local/bin；请打开新的 shell 以便其出现在 PATH 中）。在任何操作系统上，请使用上文 uv 官方安装器 — 不要使用 pip install uv，后者可能不会创建 uvx 命令，并可能将 uv 隐藏在客户端无法访问的环境中。

⚠️ 在安装 UV 之前请勿继续

让客户端找到 uvx

从 GUI 启动的 MCP 客户端（Claude Desktop、Cursor、从 Dock/开始菜单启动的 VS Code）不会继承终端的 PATH，因此裸写的 "command": "uvx" 可能会报 spawn uvx ENOENT，尽管在终端中 uvx 可以正常工作。若出现此情况：

查找 uvx 的完整路径 — which uvx（macOS/Linux）或 where uvx（Windows）— 并将其用作 "command"，例如 /opt/homebrew/bin/uvx 或 C:\Users\<you>\.local\bin\uvx.exe。
在 Windows 上也可以改为包装为："command": "cmd", "args": ["/c", "uvx", "blender-mcp"]。
在更改任何 PATH 或配置后，请完全退出并重新启动客户端（Windows：从系统托盘退出，而非仅关闭窗口；macOS：Cmd-Q）。

固定 Python 版本（避免 conda / pyenv / 版本冲突）

uv 会选择运行服务器的 Python 解释器。在装有 conda（自动激活 base）、pyenv 或 asdf 的机器上 — 或安装了某些依赖尚无 wheel 的较新 CPython 版本时 — uv 可能会选取导致安装失败的解释器。请固定使用 Python 3.11，并优先使用 uv 管理的解释器，以避免使用 PATH 上的任意版本：

{
    "mcpServers": {
        "blender": {
            "command": "uvx",
            "args": ["--python", "3.11", "blender-mcp"],
            "env": { "UV_PYTHON_PREFERENCE": "only-managed" }
        }
    }
}

--python 3.11 仍满足本包的 requires-python >=3.10 要求，而 UV_PYTHON_PREFERENCE=only-managed 可防止 uv 优先选择 conda、pyenv、asdf 或系统 Python。（仓库中的 .python-version 仅供贡献者参考，不会影响 uvx。）若修复后仍反复重放之前的失败尝试，请清除缓存：uv cache clean blender-mcp && uvx --refresh blender-mcp。

若 uv 无法使用：不使用 uv 安装

在受限机器上，可完全跳过 uvx，使用 pipx,，然后将客户端指向已安装的命令：

pipx install blender-mcp
pipx ensurepath          # then restart your shell / client

将得到的绝对路径用作 "command"（使用 which blender-mcp / where blender-mcp 查找），并省略 args。

环境变量

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

BLENDER_HOST：Blender socket 服务器的主机地址（默认："localhost"）
BLENDER_PORT：Blender socket 服务器的端口号（默认：9876）

示例：

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

Claude for Desktop 集成

观看设置说明视频（假设你已安装 uv）

前往 Claude > Settings > Developer > Edit Config > claude_desktop_config.json，加入以下内容：

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

Claude Code

使用 Claude Code CLI 添加 blender MCP 服务器：

claude mcp add blender uvx blender-mcp

Cursor 集成

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 设置视频

⚠️ 仅运行一个 MCP 服务器实例（在 Cursor 或 Claude Desktop 中二选一），不要同时运行两者

Visual Studio Code 集成

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

OpenCode 集成

{
  "mcp": {
    "blender-mcp": {
      "type": "local",
      "command": ["uvx", "blender-mcp"],
      "enabled": true,
      "environment": {
        "BLENDER_HOST": "localhost",
        "BLENDER_PORT": "9876"
      }   
    }
  }
}

安装 Blender 插件

从本仓库下载 addon.py 文件
打开 Blender
前往 Edit > Preferences > Add-ons
点击 "Install..." 并选择 addon.py 文件
勾选 "Interface: Blender MCP" 旁的复选框以启用该插件

用法

启动连接

在 Blender 中，打开 3D View 侧边栏（若不可见，请按 N）
找到 "BlenderMCP" 标签页
若需从其 API 获取资产，可勾选 Poly Haven 复选框（可选）
点击 "Connect to Claude"
确保 MCP 服务器已在终端中运行

在 Claude 中使用

在 Claude 上完成配置文件设置，且 Blender 中插件已运行后，你将看到带有 Blender MCP 工具的锤子图标。

功能

获取场景与物体信息
创建、删除和修改形状
为物体应用或创建材质
在 Blender 中执行任意 Python 代码
通过 Poly Haven 下载合适的模型、资产和 HDRI
通过 Hyper3D Rodin 生成 AI 3D 模型

示例命令

以下是一些可让 Claude 执行的示例：

"Create a low poly scene in a dungeon, with a dragon guarding a pot of gold" Demo
"Create a beach vibe using HDRIs, textures, and models like rocks and vegetation from Poly Haven" Demo
Give a reference image, and create a Blender scene out of it Demo
"Generate a 3D model of a garden gnome through Hyper3D"
"Get information about the current scene, and make a threejs sketch from it" Demo
"Make this car red and metallic"
"Create a sphere and place it above the cube"
"Make the lighting like a studio"
"Point the camera at the scene, and make it isometric"

Hyper3D 集成

Hyper3D 的免费试用密钥（free trial key）每天可生成有限数量的模型。若达到每日上限，可等待次日重置，或从 hyper3d.ai 和 fal.ai 获取你自己的密钥。

持久化 API 凭据

BlenderMCP 支持通过 Blender 插件偏好设置（Add-on Preferences）保存持久化凭据：

Edit -> Preferences -> Add-ons -> Blender MCP

你可以将以下值保存在该处，以便在 Blender 重启后仍然保留：

Sketchfab API Key
Hyper3D API Key
Hunyuan3D SecretId / SecretKey
Hunyuan3D API URL

对于无界面（headless）环境或 CI，也可通过环境变量注入凭据：

BLENDERMCP_SKETCHFAB_API_KEY
BLENDERMCP_HYPER3D_API_KEY
BLENDERMCP_HUNYUAN3D_SECRET_ID
BLENDERMCP_HUNYUAN3D_SECRET_KEY
BLENDERMCP_HUNYUAN3D_API_URL

故障排除

连接问题：确保 Blender 插件服务器正在运行，且 Claude 上已配置 MCP 服务器；请勿在终端中运行 uvx 命令。有时第一条命令可能无法通过，但之后通常会开始正常工作。
超时错误：尝试简化请求，或将其拆分为更小的步骤
Poly Haven 集成：Claude 的行为有时不太稳定
试过重启了吗？：若仍有连接错误，请尝试同时重启 Claude 和 Blender 服务器

技术细节

通信协议

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

命令以 JSON 对象发送，包含 type 及可选的 params
响应为 JSON 对象，包含 status 以及 result 或 message

限制与安全注意事项

execute_blender_code 工具允许在 Blender 中运行任意 Python 代码，功能强大但可能存在风险。在生产环境中请谨慎使用。使用前务必保存你的工作。
Poly Haven 需要下载模型、纹理和 HDRI 图像。若不想使用，请在 Blender 中取消勾选相应复选框。
复杂操作可能需要拆分为更小的步骤

遥测控制

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

在 Blender 中：前往 Edit > Preferences > Add-ons > Blender MCP，取消勾选遥测同意复选框
- 同意（已勾选）：收集匿名化的提示词、代码片段和截图
- 不同意（未勾选）：仅收集最少的匿名使用数据（工具名称、成功/失败、耗时）
环境变量：通过运行以下命令完全禁用所有遥测：

DISABLE_TELEMETRY=true uvx blender-mcp

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

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

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

贡献

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

免责声明

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