BlenderMCP

通过自然语言实时控制 Claude AI 操作 Blender 3D

🌐 官方网站 · 📹 教程 · 💬 Discord · 📖 维基 · 📋 更新日志

BlenderMCP 通过 Model Context Protocol 将 Blender 3D 与 Claude AI（以及其他任何 LLM）相连接。它支持通过提示词驱动 3D 建模、场景创建和实时对象操控 — 直接通过您的 AI 助手实现。

目录

• 功能特性
• 更新内容
• 快速入门
• 安装说明
• 使用方法
• 集成服务
• API 凭证
• 故障排除
• 技术细节
• 安全与遥测
• 贡献者
• 社区交流
• 贡献指南

功能特性

更新内容

完整更新日志：Releases

• Hunyuan3D 3D 模型生成
• 用于场景理解的视口截图功能
• Sketchfab 模型搜索与导入
• Poly Haven 资源集成
• Hyper3D Rodin AI 模型生成
• 远程主机支持

从旧版本更新：

1. 下载最新的 addon.py 并替换 Blender 中的旧文件
2. 在客户端配置中移除并重新添加 MCP 服务器

快速入门

# macOS
brew install uv

添加到 Claude > 设置 > 开发者 > 编辑配置 > claude_desktop_config.json：

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

安装 Blender 插件，点击 连接，然后开始输入提示词。

安装

前提条件

安装 uv：

brew install uv

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")

curl -LsSf https://astral.sh/uv/install.sh | sh

请勿使用 pip install uv — 这可能无法创建 uvx 命令。

客户端未找到 uvx

GUI 客户端不会继承终端的 PATH。请获取完整路径：

• 在 macOS/Linux 上使用 which uvx，在 Windows 上使用 where uvx
• 在配置中将其用作 "command"
• Windows 系统："command": "cmd", "args": ["/c", "uvx", "blender-mcp"]
• 修改配置后，请完全退出并重新启动客户端

Apple Silicon（M1/M2/M3/M4）架构不匹配

如果在 arm64 架构的 Mac 上，uvx 尝试为 x86_64 架构进行构建（出现 cryptography wheel 错误），请强制使用 arm64 架构的 Python：

"args": ["--python", "3.11-aarch64", "blender-mcp"]

Docker / WSL / 远程主机

Blender 必须监听 MCP 进程能够访问的位置：

"env": {
  "BLENDER_HOST": "host.docker.internal",
  "BLENDER_PORT": "9876"
}

在 WSL2 中与 Windows Blender 通信时，请尝试使用 BLENDER_HOST=127.0.0.1 或你的 Windows 主机 IP。截图将以 base64 格式返回（无需共享临时路径）。

Blender 版本

支持 Blender 3.0 及更高版本；推荐使用 4.x / 5.x。请使用常规的 GUI Blender 会话（而非 blender -b 后台模式），以确保 MCP 套接字和视口工具正常工作。

Claude 桌面版

观看设置视频

Claude > 设置 > 开发者 > 编辑配置 > claude_desktop_config.json：

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

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

pipx install blender-mcp
pipx ensurepath

光标

观看光标设置视频

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

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

一次仅运行一个 MCP 服务器 —— 可以是 Cursor 或 Claude 桌面版，但不能同时运行两者。

VS Code

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

开放代码

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

Claude 代码命令行界面

claude mcp add blender uvx blender-mcp

Blender 插件

1. 下载 addon.py
2. 在 Blender 中：编辑 > 偏好设置 > 插件 > 安装...
3. 选择 addon.py
4. 启用 "界面：Blender MCP"

使用方法

建立连接

1. 打开 3D 视图侧边栏（若未显示，按 N 键）
2. 进入 BlenderMCP 选项卡
3. （可选）启用 Poly Haven 以进行资源下载
4. 点击 连接到 Claude

连接成功后，Claude 会显示锤子图标，确认 Blender 工具已激活：

示例提示词

集成功能

Poly Haven

下载 HDRI、纹理和 3D 模型。在 BlenderMCP 侧边栏中启用。

Hyper3D Rodin

AI 3D 模型。免费试用有每日限制 — 可在 hyper3d.ai 或 fal.ai 获取您自己的密钥。

混元3D（Hunyuan3D）

腾讯 3D 生成。在 Blender 插件偏好设置中配置凭证。

Sketchfab

搜索并将 3D 模型导入您的场景。

API 凭证

在 编辑 > 偏好设置 > 插件 > Blender MCP 中存储，以便在重启后保持：

export BLENDER_HOST=localhost
export BLENDER_PORT=9876

故障排除

which uvx   # macOS / Linux
where uvx   # Windows

在配置中将该完整路径用作 "command"。

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

清除缓存：uv cache clean blender-mcp && uvx --refresh blender-mcp

技术详情

LLM Client  <-- MCP -->  MCP Server (src/blender_mcp/server.py)  <-- TCP:9876 -->  Blender Addon (addon.py)

TCP 套接字上的 JSON：

{ "type": "create_object", "params": { "type": "SPHERE", "name": "Ball" } }
{ "status": "success", "result": { "name": "Ball", "location": [0, 0, 0] } }

安全性与遥测

execute_blender_code 会在 Blender 中运行任意 Python 代码。使用前请保存您的工作。

为帮助改进项目，可能会发送可选的匿名使用统计数据（工具名称、成功状态/持续时间、版本/平台）。详细信息（提示词/代码/截图）需要勾选插件隐私复选框。上传前会剥离类似凭据的字符串。

完全禁用方法：

BLENDER_MCP_DISABLE_TELEMETRY=true uvx blender-mcp

或者在客户端配置中："env": { "BLENDER_MCP_DISABLE_TELEMETRY": "true" }

在 Blender 中：编辑 → 偏好设置 → 插件 → Blender MCP → 遥测复选框。

贡献者

_{使用 contrib.rocks 制作}

社区

支持者： CodeRabbit

贡献指南

1. Fork 本仓库
2. 创建分支：git checkout -b feature/your-feature
3. 提交并创建 PR

详见 CONTRIBUTING.md 和 TERMS_AND_CONDITIONS.md。

许可证

MIT — 详见 LICENSE。

星标历史