BlenderMCP 使用教程

📖 项目简介

MCP for Blender（仓库名 blender-mcp，安装包名 mcp-for-blender）是 Siddharth Ahuja 开源的 Blender 插件，协议 MIT。它让 Codex 用一句话直接改你打开的那个 Blender 文件：建物体、上材质、打灯光、摆相机。

它分成两截。Blender 里装一个插件，按 N 键打开侧边栏，点一下启动，本机开一个端口。另一截是 MCP 服务，用 uvx 拉起来，接到 Codex。两边用本地 socket 说话，默认地址是本机 9876 端口。模型不猜按钮，而是调用读场景、改物体、跑 Python、导文件这些工具。

官方 README 已经写了 Codex 的接法，命令行、桌面端、编辑器插件共用同一份配置。素材这边能搜 Poly Haven 的 HDRI 和材质（不用注册），也能把场景导出成 GLB 或 FBX。视频里的地牢和海滩，是作者公开演示里搭出来的效果。

📎 相关链接（点击展开）

GitHub 仓库：
https://github.com/ahujasid/blender-mcp

uv 官方安装器（不要用 pip 装 uv）：
https://docs.astral.sh/uv/getting-started/installation/
Windows 一条命令：powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

作者演示：
地牢龙、Poly Haven 海滩，都在仓库 README 的 Example Commands 里。

更多教程：关注公众号 / 抖音 / 视频号「IT小圈」

✨ 核心亮点

💬

一句话改场景

说「做一个低模地牢，一条龙守着一罐金子」，它在当前 Blender 文件里建物体、上材质、打灯。

🐍

能跑 Blender Python

内置工具不够用时，直接执行 bpy 代码。动手前先保存，这段代码权限很大。

🌄

素材库直接进场景

Poly Haven 大约 2400 个 HDRI、材质和模型，不用注册。勾选侧边栏开关即可。

📦

导出给别的软件

场景、选中物体或指定名字的物体，可以导出 GLB 或 FBX。

🧩 它能做什么、输出什么

项目	说明
输入	自然语言。也可以给参考图，让它照着搭。官方示例包括地牢、海滩、改车漆、影棚灯光、等轴相机。
适用类型	低模场景、灯光材质、相机、从素材库摆模型。精细角色和复杂绑定不适合指望一句话。
输出	直接改当前 .blend。可导出 GLB / FBX。
语言 / 兼容	提示词中英文都行。客户端官方写了 Codex、Claude、Cursor、VS Code 等。Blender 3.0 及以上。
规格 / 容量	一次只接一个客户端。默认端口 9876。Poly Haven 约 2400 个 CC0 资产；Poly Pizza 低模需要自己的 key，本教程不展开。

🖥️ 环境要求

环境	建议配置
操作系统	Windows、macOS、Linux。本教程按 Windows 写。
运行环境	Blender 3.0 或更新；Python 3.10 或更新；uv（用官方安装器，不要 pip install uv）。
硬件	能流畅打开 Blender 即可。建模在本机 Blender 里跑，不额外吃一张显卡做推理。文字生成 3D 模型（Hyper3D / 混元）走对方接口，本机不需要下载大模型。
低配方案	用低模和基础几何体，别一上来做人物。视口用材质预览就够看效果。
关键依赖	uvx 命令。从图形界面启动的 Codex 常常找不到 uvx，配置里要写 uvx.exe 的完整路径。

🚀 如何使用

💡

先装 uv，再在 Blender 里启用插件并点启动，最后给 Codex 注册。三步都通了，再说话。

安装 uv

用官方安装器，不要用 pip。装完新开一个终端，输入下面这行，能打出路径才算成功。Windows 安装器地址在文末折叠链接里。

                        powershell
                        uvx --version
                    

在 Blender 里装插件

在 GitHub 搜索 ahujasid/blender-mcp，下载仓库，找到 addon.py。Blender 里：编辑 → 偏好设置 → 插件 → 安装，选中这个文件并启用。回到 3D 视口按 N，打开「MCP for Blender」标签，勾上要用的能力（要用素材库就勾 Poly Haven），点启动。按钮文案以你看到的为准，旧文档里写的是 Connect to Claude。

                        text
                        N 键 → MCP for Blender → 勾选能力 → 点启动
                    

跑通最小例子

先保存当前 Blender 文件。在 Codex 里说一句具体的话，例如下面这句。看到墙、火把、物体冒出来，就通了。说完如果没反应，先看 Blender 侧边栏是不是已经启动。

                        text
                        做一个低模地牢，一条龙守着一罐金子
                    

侧边栏开关：

开关	作用
启动服务	在本机 9876 端口等 Codex 连过来。不点这个，后面全部没反应。
Poly Haven	允许搜索并导入 HDRI、材质、模型。不勾，它不会自己去拖素材。
执行代码	允许在 Blender 里跑任意 Python。开着的时候，动手前先保存。

进阶：导出和素材

场景像样之后，让它导出给游戏引擎或其他软件。要用海滩、夜景这类光照，把 Poly Haven 打开，再说「用阴天 HDRI 打光，墙换成锈金属」。

                        text
                        把当前场景导出成 GLB
                    

结合 Codex 使用

命令行、桌面端、编辑器插件读的是同一份配置。注册之后重启 Codex，在工具列表里看到 blender 且是启用状态。Windows 上如果报找不到 uvx，把 command 改成 uvx.exe 的完整路径（一般在用户目录的 .local\bin 下），录屏时把用户名遮掉。

                        powershell
                        codex mcp add blender -- uvx mcp-for-blender
                    

或者写进 Codex 的 config.toml：

                        toml
                        [mcp_servers.blender]
command = "uvx"
args = ["mcp-for-blender"]
                    

✅

注册成功的标志：重启后工具列表里有 blender。然后在已经启动插件的 Blender 里说一句话，视口里开始长物体。

🎯 典型应用场景

🏰

低模场景打底

地牢、房间、街角这类用方块和柱子就能看出来的场景，一句话先搭出布局。

🏝️

用素材库布景

海滩、野外：HDRI 负责天光，石头和植被从 Poly Haven 进场景。

🎨

改已有模型

「把这辆车改成红色金属漆」「灯光改成影棚」「相机改成等轴」。

🖼️

照着参考图搭

丢一张图，让它用低模把大形和灯光关系搭出来，再自己修细节。

🎮

导出到游戏引擎

场景定稿后导出 GLB 或 FBX，拿到 Unity、Godot、Three.js 里继续用。

🔁

反复改同一句

第一版太素，就补一句「地面改成湿的、反光」。它改的是当前文件，不用重头搭。

📈 和手点 Blender 比

对比	差别
空场景搭布局	手点要自己找添加菜单、挤出、摆位置。接上之后，一句话让它拉墙、立火把、摆主体。
找 HDRI 和材质	手点要自己下文件再连节点。勾上 Poly Haven 后，它按描述搜索并导入。
不会的操作	手点卡在记不住快捷键。它可以直接跑 bpy，等于把文档查询也做了。代价是代码权限大，必须先保存。

🧠

它不是云端渲染器。建模发生在你本机已经打开的 Blender 里，所以你能看着物体一个个冒出来，也能随时接手自己改。

❓ 常见问题

Q: 和自己点 Blender 有什么不同？

你还是在用自己的 Blender 文件。区别是建物体、上材质、找素材这些操作由 Codex 通过插件执行，你负责说清楚要什么，以及最后自己修。

Q: 支持哪些 Blender 版本？

官方要求 Blender 3.0 或更新。更老的版本插件装不上。

Q: 提示找不到 uvx，或 spawn uvx ENOENT？

从开始菜单或桌面图标打开的 Codex 不继承终端的 PATH。把配置里的 command 改成 uvx.exe 的完整路径，然后重启 Codex。先在新终端里确认 uvx --version 能跑。

Q: 说了话，Blender 里没反应？

先看三件事：插件启用了没有、侧边栏点过启动没有、Codex 工具列表里 blender 是不是启用。一次只能有一个客户端连着。端口默认 9876，被别的程序占用时要先关掉那个程序。

Q: 旧命令 uvx blender-mcp 还能用吗？

能。新装请用 mcp-for-blender。仓库和说明都已经改名，两个名字指的是同一个项目。

Q: 怎么和 Codex 接？

一条命令：codex mcp add blender -- uvx mcp-for-blender。然后重启。命令行、桌面端、编辑器插件共用这一份配置。

Q: 它和 Blender 官方有关系吗？

没有。这是第三方插件，通过 Blender 自己的 Python 接口操作场景。出问题不会影响你没保存的其他文件，但当前文件如果没保存，执行代码可能改坏它。

Q: 可以商用吗？

插件本身是 MIT。Poly Haven 导入的资产是 CC0，可以商用、不必署名。别的素材库（例如 Poly Pizza 里大量 CC-BY）要看单件的许可证，导入后属性里会写着。本教程不把「能不能卖」当成功能来讲。