Blender MCP 完整安装教程

Blender MCP 完整安装教程

官方项目：Blender Foundation / Blender Lab 团队维护的官方 MCP 集成 核心功能：让大语言模型（LLM）通过自然语言直接控制 Blender，实现场景分析、物体操作、Python 脚本执行、渲染等 协议：Model Context Protocol（MCP），兼容所有支持 MCP 标准的 LLM 客户端

一、整体架构说明

Blender MCP 由 三个独立组件 协同工作，缺一不可：

┌─────────────┐ stdio / TCP ┌──────────────┐ TCP:9876 ┌───────────┐
│ LLM 客户端 │ ◄──────────────────► │ MCP Server │ ◄──────────────► │ Blender │
│ (Claude等) │ │ (blender-mcp) │ │ (+插件) │
└─────────────┘ └──────────────┘ └───────────┘

二、环境要求

⚠️ 重要：Blender 版本必须 ≥ 5.1，低版本不支持该扩展体系。

三、安装步骤

步骤 1：安装前置依赖（uv + Git）

1.1 安装 uv

uv 是运行 MCP Server 必需的 Python 包管理器。

Windows（PowerShell）：

powershell –ExecutionPolicy ByPass –c "irm https://astral.sh/uv/install.ps1 | iex"

macOS / Linux：

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

安装完成后验证：

uv –version

1.2 安装 Git

• Windows：从 git-scm.com 下载安装
• macOS：xcode-select –install
• Linux：sudo apt install git（Ubuntu/Debian）

步骤 2：安装 Blender 插件

方式 A：拖拽安装（推荐，可接收更新通知）

搜索框输入 mcp，找到 MCP 扩展，点击 安装（Install）

💡 为什么要拖两次？ 第一次拖拽只是注册 Blender Lab 仓库，第二次才是真正安装插件。这是 Blender 扩展平台的标准流程。

方式 B：从磁盘安装

步骤 3：启用插件并启动 MCP 服务

✅ 验证：看到红色的 Stop MCP Server 按钮和绿色对勾 Server is running，说明插件端已就绪。

步骤 4：安装 MCP Server（blender-mcp）

MCP Server 是独立于 Blender 的进程，负责在 LLM 客户端和 Blender 插件之间转发消息。

方式 A：源码安装（通用，推荐）

# 克隆官方仓库
git clone https://projects.blender.org/lab/blender_mcp.git

# 进入 mcp 子目录并安装
cd blender_mcp/mcp
pip install .

或者使用 uv 直接运行（无需全局安装）：

uv –directory /path/to/blender_mcp/mcp run blender-mcp

方式 B：MCP Bundle（.mcpb）

适用于支持 .mcpb 格式的新版客户端：

⚠️ 注意：Llama.cpp 目前 不支持 .mcpb 格式，请使用源码安装方式。

步骤 5：配置 LLM 客户端

MCP 遵循开放标准，可对接任意支持 MCP 的客户端。以下以常见客户端为例：

5.1 Claude Code

# 安装 Claude Code
npm i -g @anthropic-ai/claude-code

# 添加 MCP Server
claude mcp add blender — \\
uv –directory /path/to/blender_mcp/mcp run blender-mcp

# 重启 Claude Code 后验证
claude
# 在交互界面输入 /mcp 查看已连接的服务器

5.2 通用 JSON 配置（适用于 Griptape Nodes 等）

在客户端的 MCP 服务器配置中添加：

{
"transport": "stdio",
"command": "uv",
"args": [
"–directory",
"/path/to/blender_mcp/mcp",
"run",
"blender-mcp"
],
"env": {},
"cwd": null,
"encoding": "utf-8",
"encoding_error_handler": "strict"
}

⚠️ 路径注意：–directory 必须指向仓库内的 mcp/ 子目录，不是仓库根目录！

5.3 Llama.cpp / 其他本地客户端

请参考 Llama.cpp 官方文档 中关于 MCP Server 的配置说明，将上述 uv run blender-mcp 命令填入对应配置项。

四、快速验证

完成以上步骤后，按以下顺序验证：

五、常见问题与排错

❌ 连接被拒绝（Connection Refused）

原因：Blender 内的 MCP 服务未启动。 解决：

❌ 第一次命令总是失败

原因：已知的初始化延迟问题。 解决：重新发送一次命令即可。首次连接后服务需要短暂初始化。

❌ 路径错误 / 找不到 blender-mcp

原因：–directory 参数指向了错误路径。 解决：

• 确认路径指向 blender_mcp/mcp/ 子目录，不是 blender_mcp/ 根目录
• 示例正确路径：/Users/name/Documents/GitHub/blender_mcp/mcp

❌ 超时错误（Timeout）

原因：请求过于复杂或模型响应慢。 解决：

• 将复杂任务拆分为多个小步骤
• 增加客户端的超时配置
• 先用简单指令（如"列出场景物体"）测试连通性

❌ uv 命令找不到

原因：uv 未正确安装或未加入 PATH。 解决：

• 重新运行安装脚本
• 重启终端 / 命令行窗口
• Windows 用户可能需要重启电脑使 PATH 生效

❌ Blender 版本不兼容

原因：使用了 Blender 5.1 以下版本。 解决：升级到 Blender 5.1 或更高版本，从 blender.org 下载。

❌ 插件安装后搜索不到

原因：仓库源未正确添加。 解决：

• 确认拖拽操作执行了 两次
• 检查 获取扩展 → 仓库（Repositories） 中是否有 lab.blender.org
• 如无，手动添加仓库：https://lab.blender.org/api/extensions/

六、安全提示

⚠️ 重要安全警告

Blender MCP Server 会在 Blender 中直接执行 LLM 生成的 Python 代码，且没有沙箱防护。这意味着：

• 模型可以删除场景数据、修改文件、访问网络
• 恶意提示词可能导致数据丢失或系统风险

安全建议：

七、能力清单（MCP Server 提供的工具）

八、常用指令示例

# 场景分析
"分析当前场景，找出面数最高的前5个物体"
"列出所有未关联到任何场景的物体"

# 建模操作
"创建一个半径为2的球体，放在立方体上方"
"给所有选中物体添加细分修改器，级别设为2"

# 灯光相机
"把灯光调整为影棚布光效果"
"将相机对准场景中心并切换为等轴测视图"

# 数据管理
"给所有数据块起一个描述性名称，如果可以的话直接应用"
"导出当前场景信息为 JSON"

九、参考资源

十、安装流程速查表

□ 1. 安装 uv（包管理器）
□ 2. 安装 Git
□ 3. 安装 Blender 5.1+
□ 4. 访问 blender.org/lab/mcp-server，拖拽两次安装插件
□ 5. 启用插件 → Start MCP Server → 确认 Server is running
□ 6. git clone https://projects.blender.org/lab/blender_mcp.git
□ 7. pip install ./blender_mcp/mcp
□ 8. 在 LLM 客户端中配置 MCP Server（uv run blender-mcp）
□ 9. 重启客户端，用 /mcp 确认连接
□ 10. 测试："当前场景中有哪些物体？"

教程版本：v1.0 | 更新日期：2026-09-07 适用版本：Blender 5.1+ / Blender Lab MCP Server 1.0+