Showing Posts From
Blender
-
BrodyGao - 2026/10/23
Blender MCP 完全上手:官方 Llama.cpp 与 OpenCode 两种接入方式
如果你正在测试 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.gguf Qwen3.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.0Blender 侧组件 官方 Add-on(扩展商店) 自带 Add-on(socket server)MCP Server 分发 从源码 clone + uv 跑 PyPI 包,uvx 一行拉起工具数量 20 个(偏场景读取 / 导航 / 渲染) 9 个(偏建模 / 资产 / 生成 / 视觉)资产库 无 Poly Haven、Sketchfab、Poly PizzaAI 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 TerminalMCP 配置方式 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(.mcpb Bundle / 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 官方页面与社区项目仓库,版权归原作者所有,仅作技术说明用途。