Blender MCP 完全上手:官方 Llama.cpp 与 OpenCode 两种接入方式
-
BrodyGao - 2026/10/23
如果你正在测试 Blender MCP(Model Context Protocol),目前常见有两种使用方式:
- 官方 Llama.cpp Web UI 方式
- OpenCode 接入 MCP 方式
两者本质上都是让大模型调用 Blender MCP Server,只是客户端不同。
这篇教程把官方 Wiki 的内容补全成可以照着敲的完整流程,再补上社区插件 mcp-for-blender 这条分支,以及官方 Add-on 的安装细节。
先看官方的架构长什么样——理解了这一层,后面的命令就都顺理成章了。

一、先搞懂架构:官方 Blender MCP 是「两个组件」
Blender 官方 MCP Server 不是一个东西,而是两个独立组件:
| 组件 | 位置 | 职责 |
|---|---|---|
| MCP Add-on | 装在 Blender 里 | 在 Blender 进程内开一个 TCP socket 服务,接收并执行请求 |
| blender-mcp | 独立 Python 进程 | 由 MCP 客户端启动,实现 MCP 协议,把请求转发给 Add-on |
官方仓库 README 里画的数据流非常清楚:
MCP Client ⇐ MCP/stdio ⇒ blender-mcp ⇐ TCP socket ⇒ Blender Add-on
这条链路解释了几件很关键的事:
- 你必须同时装 Add-on 和 MCP Server,缺一不可。只装其中一个,客户端连上去会直接失败。
- 两者的通信端口是 9876(Add-on 侧监听,默认
localhost)。这个端口在官方 Add-on 和社区插件里是同一个默认值,所以两者不能同时跑。 - MCP 客户端和 blender-mcp 之间才有「传输方式」的选择(stdio / Streamable HTTP),Add-on 和 blender-mcp 之间永远是本机 TCP socket。
再补一个官方页面反复强调的前提:
Blender does not have any built-in functionality for connecting to LLMs.
Blender 自己不内置任何 LLM 连接能力。要接 AI,官方给出的清单是:Blender 5.1+、Add-on、兼容 MCP 的 LLM 客户端、MCP Server 本体——三样外部工具都要你自己装。
二、方案一:官方 Llama.cpp 方式(纯本地,最快跑通)
适合人群: 想快速体验 MCP,希望纯本地运行,不依赖 VS Code 或 OpenCode。
1. 安装 Llama.cpp
# Windows
winget install llama.cpp
# macOS / Linux
brew install llama.cpp
官方建议使用较新的版本(>= 8218)。Llama.cpp 是命令行工具,Windows 用 PowerShell,Mac/Linux 用系统自带终端。
2. 下载模型
官方测试过的模型:
| 模型 | GGUF 下载 | 特点 |
|---|---|---|
| Gemma 4 | unsloth/gemma-4-26B-A4B-it-GGUF | 26B 总参 / A4B 激活,MoE 架构 |
| Qwen 3.6 | unsloth/Qwen3.6-35B-A3B-GGUF | 35B 总参 / A3B 激活 |
在 M3 MacBook 上官方实测过这两个具体量化版本:
gemma-4-26B-A4B-it-MXFP4_MOE.ggufQwen3.6-35B-A3B-Q5_K_M.gguf
模型必须同时满足三个条件:支持 Tool Calling、支持 MCP、代码生成能力强。这一点很关键——Blender MCP 的工作方式就是「让模型写 Python 丢给 Blender 执行」,模型不会写代码或者不会调工具,整条链路就是空转的。
3. 安装官方 Add-on(这一步官方 Wiki 讲得最简,实际最有坑)
官方 Add-on 位于 Blender Lab,v1.0.3,最低要求 Blender 5.1.0。
方式 A:拖放安装(推荐)
把 .zip 直接拖进 Blender 窗口。官方特别提醒:需要拖两次。
If you drag & drop into Blender you will need to do it twice. First to add the Blender Lab repository, secondly to install the add-on itself.
第一次拖放是把 Blender Lab 扩展仓库(https://lab.blender.org/)加进 Blender 的仓库列表,第二次才是真正安装 MCP Add-on 本身。走仓库方式的好处是新版本发布时你能收到更新通知。
方式 B:从磁盘安装
下载 mcp-1.0.3.zip 后,在 Blender 的扩展管理界面用 Install from Disk。
装完别急着跑,有两件事必须做:
- 在偏好设置里启用网络访问。Add-on 要开本地 TCP socket,如果系统级「Online Access」没开,Blender 会在偏好设置面板里报
Online access must be enabled in the system preferences,而且是静默失败——不报错你只会看到连不上。这个坑官方文档没写,但从 Add-on 源码里能确认。 - 确认端口和自动启动。在
Edit → Preferences → Add-ons → MCP里能看到 Host / Port / Auto Start / Log 等选项。默认localhost:9876,Auto Start 默认开启(延迟 1 秒启动,避免拖慢 Blender 启动),面板底部有 Start / Stop 按钮和运行状态指示灯。
官方 Add-on 还支持后台模式,blender --background file.blend --command blender_mcp 可以在无界面下起服务(此时延迟响应不支持,命令必须同步完成)。
4. 下载 Blender MCP Server
# Windows
cd c:\
git clone https://projects.blender.org/lab/blender_mcp.git
# macOS / Linux
cd $HOME
git clone https://projects.blender.org/lab/blender_mcp.git
这会把 MCP Server 下载到 C:\blender_mcp 或 $HOME/blender_mcp。
5. 启动 Llama.cpp
llama-server -m ./Qwen3.6-35B-A3B-Q5_K_M.gguf
也支持 --hf-repo 和 --hf-file 让 llama 自己下载模型。
6. 启动 MCP Server(HTTP 传输)
# Windows
uv --directory C:\blender_mcp\mcp run blender-mcp --transport http --port 9191
# macOS / Linux
uv --directory $HOME/blender_mcp/mcp run blender-mcp --transport http --port 9191
关于 uv:它是 Astral 的 Python 包管理器,uv --directory <路径> run <命令> 的意思是「切到这个目录,用这个目录里的项目环境执行命令」,避免你手动建 venv、装依赖。首次运行会自动解析 mcp/pyproject.toml 并装好依赖。
注意 9191 和 9876 的分工:9191 是 MCP Server 对外的 HTTP 端点(客户端连它),9876 是 MCP Server 回连 Blender Add-on 的端口(Add-on 监听它)。
7. 在 Web UI 里配置 MCP
打开 http://127.0.0.1:8080,你会看到 llama.cpp 的聊天界面。

点击左下角 + → MCP Servers → Manage MCP Servers,然后:
- 点
+ Add New Server - Server URL 填
http://127.0.0.1:9191/ - 点 Add → Save settings
保存后会看到 blender-mcp 出现在列表里,带 HTTP 徽章、Tools / Resources / Prompts 三个标签。

之后在聊天框点 +,MCP Servers 一栏就能勾选 blender-mcp,直接开聊:
Create a cube in Blender
Generate a sci-fi scene in Blender
模型会自动调用 blender-mcp 执行对应操作。
官方 MCP Server 提供的能力(源码里 mcp/blmcp/tools/ 下共 20 个工具模块)大致分四类:
- 场景读取:
get_blendfile_summary_datablocks、get_objects_summary、get_object_detail_summary、get_blendfile_summary_missing_files - 执行代码:
execute_blender_code - 视觉反馈:
get_screenshot_of_area_as_image、get_screenshot_of_window_as_image、render_thumbnail_to_path、render_viewport_to_path - 界面导航:
jump_to_tab_by_name、jump_to_view3d_object_by_name
还有两个容易被忽略但很值钱的东西:
- 内置文档检索——
search_api_docs和search_manual_docs能查 Blender Python API 参考和用户手册,模型写bpy代码时不用凭记忆瞎猜参数。 - 内置 prompt——连接时会下发一份初始指令,其中明确要求「先检查场景再动手,不要在未确认的情况下破坏性修改对象」,以及「优先用
bpy.ops而不是裸bpy.data」。
官方还给了几个很能说明问题的示例提示词,比如:
Analyze the scene and list the outliers: objects with highest polygon count
but smaller size from the camera point of view.
用官方 Classroom 演示文件跑,它能识别出 coat 1 约 37k 面数、alphabet 约 20k 面数,并告诉你 coat 1 的面数翻倍来自 Solidify 修改器。
再比如让它给 Geometry Nodes 生成文档:
With the current open Blender file explain what the main geometry nodes
setup is doing. Add inline documentation for it with frame elements.
它会创建带颜色编码的文档帧和一份 Text 数据块:

三、方案二:OpenCode 方式(stdio 传输,开发者日常)
适合人群: 已经在用 OpenCode,想统一管理多个 MCP Server。
这里要先纠正一个很常见但错误的配置格式。
网上(包括不少中文教程)会教你这样写:
{
"mcpServers": {
"blender": {
"command": "uv",
"args": ["--directory", "/Users/yourname/blender_mcp/mcp", "run", "blender-mcp"]
}
}
}
这是 Claude Desktop / Cursor 那一类客户端的通用格式,不是 OpenCode 的。OpenCode 官方文档里的顶层键是 mcp,每个服务器要显式声明 type,command 是数组而不是 {command, args} 对象。
OpenCode 的配置文件位置:
| 作用域 | 路径 |
|---|---|
| 全局 | ~/.config/opencode/opencode.json |
| 项目级 | 项目根目录的 opencode.json(可以安全提交到 Git) |
正确的配置
编辑 ~/.config/opencode/opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"blender": {
"type": "local",
"command": [
"uv",
"--directory",
"/Users/yourname/blender_mcp/mcp",
"run",
"blender-mcp"
],
"enabled": true
}
}
}
Windows 只需改路径(注意 JSON 里反斜杠要转义):
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"blender": {
"type": "local",
"command": [
"uv",
"--directory",
"C:\\blender_mcp\\mcp",
"run",
"blender-mcp"
],
"enabled": true
}
}
}
几个注意点:
- 不要用
$HOME这类环境变量占位。不少 MCP 客户端不支持变量展开,OpenCode 也建议直接写绝对路径(/Users/yourname/...)。 - stdio 传输不需要 `—transport http —port 9191。客户端会自己拉起 blender-mcp 进程并通过标准输入输出通信,这是它和 llama.cpp 方案最大的区别。
- 想临时停掉某个 MCP,把
enabled改成false就行,不用删配置。 - 多挂几个 MCP 时留意上下文消耗。OpenCode 官方文档明确提醒:MCP 工具会占用上下文,GitHub 这类工具多的服务器很容易撑爆 context limit。建议用
tools段做按需开关:
{
"tools": {
"blender*": true,
"some-heavy-server*": false
}
}
启动
opencode
进会话后直接:
Create a cube in Blender
Generate a sci-fi scene in Blender
模型会自动调用 blender MCP Server。
验证配置是否生效:
opencode mcp list
四、方案三:社区插件 mcp-for-blender
适合人群:想要更完整的功能生态(资产库、AI 3D 生成、可视化校验),并且愿意用一个非官方实现。
项目地址:https://github.com/ahujasid/mcp-for-blender
先说清楚它的定位——README 开头就写着:
Disclaimer: This is a third-party integration and not made by Blender.
它是 MIT 许可的第三方集成,不是 Blender 官方项目。但它的功能完整度确实明显更高。
和官方方案的差异
| 维度 | 官方 Blender MCP | 社区 mcp-for-blender |
|---|---|---|
| 最低 Blender | 5.1 | 3.0 |
| Blender 侧组件 | 官方 Add-on(扩展商店) | 自带 Add-on(socket server) |
| MCP Server 分发 | 从源码 clone + uv 跑 | PyPI 包,uvx 一行拉起 |
| 工具数量 | 20 个(偏场景读取 / 导航 / 渲染) | 9 个(偏建模 / 资产 / 生成 / 视觉) |
| 资产库 | 无 | Poly Haven、Sketchfab、Poly Pizza |
| AI 3D 生成 | 无 | Tripo、Hunyuan3D、Hyper3D Rodin、Meshy |
| 视觉反馈 | 截图 / 渲染 | look 工具(多角度 / 线框 / X-ray / 动画条) |
| 内置文档 | API 参考 + 用户手册 | 无 |
| 安全模式 | 无 | BLENDER_MCP_SAFE_MODE=1 |
它最有意思的两个设计:
look工具——让 AI 能「看见」自己的作品。支持 viewport / camera / 多角度自动取景 / 动画条 / solid / material / rendered / wireframe / xray 视图,甚至能显示本地图片文件。这解决的是 AI Agent 的经典问题:光靠文本返回无法自检,能看才能改。- 资产与生成一体化——
search_assets/import_asset直接把 Poly Haven 的 2400+ 个 CC0 资产拉进场景,generate_3d一句话生成并导入 3D 模型。

上图是社区插件在 Codex 里的实际效果:左边 Agent 对话,右边是实时挂载的 Blender 视口,AI 说「Created Wooden Pyramid」的同时模型已经出现在场景里了。
安装
前置条件:Blender 3.0+、Python 3.10+、uv。
uv 必须用官方安装器装,README 特意警告不要用 pip install uv——那样可能根本不会生成 uvx 命令,或者装到 MCP 客户端看不见的虚拟环境里:
# macOS
brew install uv
# Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
winget install --id=astral-sh.uv -e
然后一条命令搞定:
# macOS / Linux
curl -LsSf https://www.mcp-for-blender.com/install.sh | sh
# Windows PowerShell
irm https://www.mcp-for-blender.com/install.ps1 | iex
这个安装脚本会自动完成:装 uv(如果需要)→ 检测 MCP 客户端 → 配置你选中的客户端 → 安装并启用 Blender Add-on → 备份被修改的配置文件(.bak)。
它能自动识别的客户端包括:Claude Desktop、Claude Code、Codex、Cursor、VS Code、Devin Desktop / Windsurf、OpenCode、Antigravity。
不想跑脚本的话,等价的手动步骤是:
# 检测客户端 + 写配置 + 装 Addon
uvx mcp-for-blender setup
# 只装 Blender Addon(复制成 blender_mcp.py 到 addons 目录)
uvx mcp-for-blender install-addon
# 查看本机检测到的 Addon 路径
uvx mcp-for-blender addon-paths
⚠️ 包名变更提示:项目以前叫
blender-mcp,现在 PyPI 包名是mcp-for-blender。旧命令uvx blender-mcp仍然能跑,不需要改已有配置,但新装建议用新名字。
OpenCode 配置
社区插件 README 给的 OpenCode 配置就是正确的 mcp 键格式:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"blender-mcp": {
"type": "local",
"command": ["uvx", "mcp-for-blender"],
"enabled": true,
"environment": {
"BLENDER_HOST": "localhost",
"BLENDER_PORT": "9876"
}
}
}
}
装完记得:完全退出并重开 AI 客户端 → 打开 Blender(Add-on 会随 Blender 启动 socket server)→ 然后直接发建模请求。
在 Blender 界面里,按 N 打开 3D 视图侧边栏,能看到 MCP for Blender 面板,里面有 Start MCP Server 按钮和端口设置。
常用环境变量
| 变量 | 默认值 | 作用 |
|---|---|---|
BLENDER_HOST | localhost | Blender socket server 地址 |
BLENDER_PORT | 9876 | Blender socket server 端口 |
BLENDER_MCP_SAFE_MODE | 关 | 设为 1 时执行前检查脚本 |
DISABLE_TELEMETRY | — | 设为 true 关闭全部遥测 |
要同时开两个 Blender 实例,就给第二个实例换一个端口(CLI 参数 --port 9877),并记得在对应实例的 Add-on 面板里改成同一个端口。
五、三种方式横向对比
| 项目 | 官方 Llama.cpp | 官方 + OpenCode | 社区 mcp-for-blender |
|---|---|---|---|
| 安装难度 | 简单 | 中等 | 中等(有脚本) |
| UI | Web 界面 | Terminal | Terminal |
| MCP 配置方式 | Web 里添加 | JSON 配置 | JSON 配置(或脚本自动写) |
| 多 MCP 管理 | 一般 | 强 | 强 |
| 开发体验 | 普通 | 优秀 | 优秀 |
| Agent 能力 | 基础 | 更强 | 更强(含视觉自检 / 资产生成) |
| 模型自由度 | 完全本地 | 由 OpenCode 决定 | 由 OpenCode 决定 |
| 适合人群 | 普通用户 | 开发者 | 要资产 / 要 AI 生成 3D 的用户 |
推荐结论:
- 只想验证 Blender MCP 是否可用 → 官方 Wiki 的 Llama.cpp Web UI 方案,部署最快,且模型完全跑在本地。
- 要长期用 MCP 工作流 → OpenCode + 官方 Blender MCP。可同时挂载多个 MCP、配置可版本管理、使用习惯和 Claude Code / Cline 接近,而且官方版本自带 API 文档检索,模型写
bpy代码的准确率明显更高。 - 要更强的「AI 动手能力」 → 社区
mcp-for-blender,重点是look视觉反馈和资产 / 3D 生成生态。
六、安全边界:必须认真看的一段
官方页面的警告原文:
The MCP server will execute LLM generated code in Blender without any guards in place to protect your data from removal or being sent to a remote location. To keep your data safe it is recommended to use a virtual machine, or a system without access to sensitive information.
翻译成人话:这套东西的本质是「让模型写的 Python 在你的 Blender 里跑」,没有任何沙箱。模型判错一次,就可能删掉你的场景、把数据发到别的地方。
具体风险点:
- 任意代码执行。官方
execute_blender_code和社区的同名工具都能跑任意 Python。 - Socket 无认证无加密。社区插件 README 明确说:任何能访问到 9876 端口的人都能在你 Blender 里跑 Python。所以只监听 localhost,绝不要暴露到公网,远程连接走 SSH tunnel。
- 没有 undo 保护。社区插件的建议很实在:ALWAYS save your work before using it.
- 官方 add-on 还需要「网络访问」权限。为了开本地 socket,Blender 的 Online Access 必须打开——这本身也放宽了一点系统级限制。
对应的防护手段:
- 用虚拟机跑 Blender,或者至少别让这台机器碰敏感数据
- 社区插件开启
BLENDER_MCP_SAFE_MODE=1(会拦截读写真文件、运行外部程序、访问网络、装常驻代码) - 手动保存 .blend 文件再开聊
- 只监听 localhost
- 官方 add-on 的偏好设置里打开 Log,能打印每次工具请求和响应状态,出了问题好回溯
顺带一提,官方 add-on 里还带了个 weak_sandbox.py 模块,说明这层防护是被官方承认的长期方向,而不是我多虑。
七、资源链接
官方
- Blender MCP 主页:https://www.blender.org/lab/mcp-server/
- 官方仓库:https://projects.blender.org/lab/blender_mcp
- Llama.cpp 接入文档:https://projects.blender.org/lab/blender_mcp/wiki/Llama.cpp
- Setup 文档(stdio 客户端):https://projects.blender.org/lab/blender_mcp/wiki/Setup
- Releases(
.mcpbBundle / Add-on zip):https://projects.blender.org/lab/blender_mcp/releases - Blender Lab 扩展仓库:https://lab.blender.org/
社区
- mcp-for-blender:https://github.com/ahujasid/mcp-for-blender
- 项目官网:https://mcp-for-blender.com/
- PyPI:https://pypi.org/project/mcp-for-blender/
客户端
- Llama.cpp:https://github.com/ggml-org/llama.cpp
- OpenCode MCP 文档:https://opencode.ai/docs/mcp-servers/
*本文所有命令与配置均来自官方 Wiki、官方仓库源码与社区项目 README 实测核对。配图取自 Blender 官方页面与社区项目仓库,版权归原作者所有,仅作技术说明用途。*