“Blender MCP”通常指 MCP for Blender,这是 Siddharth Ahuja 做的开源项目,能让 AI 智能体操控一个正在运行的 Blender。2026 年 11 月之前它叫 blender-mcp,多数教程仍用这个名字。连上之后,Claude Code、Codex、Cursor 或 Claude Desktop 可以通过聊天提示词创建和编辑物体、设置材质、查看视口、导出文件。
这篇指南讲它是什么、怎么在 Claude Code 和 Codex 里安装,以及一个完整示例:智能体在 Blender 里做一个低多边形游戏道具,导出 GLB,用 glTF-Transform 压缩,再由 three.js 在网页游戏里加载。每条命令我们都在 2026 年 11 月 21 日对照了项目 README 和官方文档。安装和示例我们自己没有运行过,所以下面描述的结果是文档说应该发生的结果。
Blender MCP 是什么
MCP(Model Context Protocol)是一种标准方式,让 AI 智能体拥有能操作其他程序的工具。MCP for Blender 有两部分:
- 一个 Blender 插件:在 Blender 内部开一个 socket 服务器(默认端口 9876),执行收到的命令。
- 一个 MCP 服务器(Python 包
mcp-for-blender):由你的智能体在后台启动,把智能体的工具调用转给插件。
智能体主要靠写 Blender Python 并在你打开的 Blender 文件里运行来干活。README 列出了九个工具。最常用的是 execute_blender_code(在 Blender 里运行 Python)、look(拍视口、相机或多角度视图,让智能体检查自己的成果)、get_scene_info(场景概要),以及 search_assets / import_asset(从 Poly Haven、Sketchfab 和 Poly Pizza 拉取模型、贴图和 HDRI)。还有 generate_3d,用 Meshy、Tripo、Hunyuan3D 或 Hyper3D Rodin 生成模型。
它不是 Blender 官方做的。 README 开头写着“This is a third-party integration and not made by Blender”,GitHub 简介也写着“Not affiliated with the official Blender Foundation.”。它采用 MIT 许可证,2026 年 11 月 21 日有 35,153 个 GitHub star。
不过 Blender 确实有自己的 MCP 服务器。 Blender 项目下的 Blender Lab 在 projects.blender.org/lab/blender_mcp 发布了一个更小的版本,文档在 blender.org/lab/mcp-server。它的 readme 称自己“deliberately small”。重点是 Blender Python API 文档、场景和文件概要、截图以及运行代码。它需要 Blender 5.1 或更新版本,采用 GPL-3.0,当时是 v1.0.3(2026 年 9 月)。它也以“Blender”的名字出现在 Claude 的连接器目录里,作者是 Blender Lab。我们在替代方案里介绍它。
你需要准备什么
- Blender 3.0 或更新版本(MCP for Blender 用,插件声明的最低版本是 3.0)。
- Python 3.10 或更新版本和 uv,也就是用
uvx运行服务器的工具。下面的一行命令安装器会帮你装好 uv。 - 一个支持 MCP 的智能体:按 README,可以是 Claude Code、Codex、Cursor、Claude Desktop、VS Code、OpenCode、Windsurf 或 Antigravity。
- 做游戏的部分:Node.js(用于 glTF-Transform)和一个 three.js 项目。
快速安装(一次配好所有客户端)
README 推荐的方式是一条命令:它会安装 uv,找出你机器上的智能体,让你选要配置哪些,并安装、启用 Blender 插件。它只会在每个配置文件里加一个 blender 条目,并为每个改动过的文件保存一份 .bak 备份。
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:
uvx mcp-for-blender setup
把网上的脚本直接管道给 shell,会以你当前用户的权限运行它。不想这样的话,就用下面的手动步骤,做的是同样的事,只是一步一步来。无论哪种方式,装完都要完全退出并重新打开你的智能体。
在 Claude Code 里安装 Blender MCP
- 安装 uv。README 给出的是:macOS 用
brew install uv,Linux 用curl -LsSf https://astral.sh/uv/install.sh | sh,Windows 用winget install --id=astral-sh.uv -e。它提醒不要用pip install uv,那样可能不会生成uvx命令。 - 在 Claude Code 里注册服务器。这是 README 里的命令:
claude mcp add blender uvx mcp-for-blender
- 检查。Claude Code 的 MCP 文档列出了
claude mcp list(显示类似“✔ Connected”的状态)和claude mcp get blender,会话里的/mcp面板显示的也是同样的信息。
默认情况下,claude mcp add 只把服务器保存给当前项目。加上 --scope user 就能在所有项目里用。文档里的通用写法是把服务器命令放在 -- 之后:claude mcp add [options] <name> -- <command> [args...]。如果你加了 --scope 或 --env 这类选项,就必须写 --。
要关闭项目的匿名使用统计,README 说要给服务器设置环境变量 DISABLE_TELEMETRY=true。在 Claude Code 里,用 --env 把它写在 -- 之前传入。
在 Codex 里安装 Blender MCP
Codex CLI、Codex 桌面应用和 IDE 扩展共用一个配置文件 ~/.codex/config.toml,所以配一次就能覆盖三者。
普通 MCP 服务器。 README 里的命令:
codex mcp add blender -- uvx mcp-for-blender
也可以手动加到 ~/.codex/config.toml:
[mcp_servers.blender]
command = "uvx"
args = ["mcp-for-blender"]
运行 codex mcp list,确认 blender 显示为已启用。工具会在你下次启动 Codex 时出现,在 Codex 终端界面里用 /mcp 可以列出正在运行的服务器。OpenAI 的 Codex MCP 文档还介绍了用于环境变量的 env 表、startup_timeout_sec(默认 10)和 tool_timeout_sec(默认 60)。在桌面应用里,进入 Settings → MCP servers → Add server,命名为 blender,选 STDIO,输入 uvx mcp-for-blender。
Codex 插件。 README 推荐 Codex 用这条路线。它会在聊天里加一个实时的 Blender 视口、Poly Haven、Sketchfab 和 Poly Pizza 的缩略图选择器,以及用 @ 提及场景物体。它还没有进入 Codex 插件目录,所以要从仓库添加:
git clone https://github.com/ahujasid/blender-mcp.git
codex plugin marketplace add ./blender-mcp/integrations/codex
然后重启 Codex,在插件目录里安装 MCP for Blender,再让 Codex 使用它。
Cursor 和其他客户端
在 Cursor 里,打开 Settings → MCP 添加一个全局服务器,或者在项目里创建 .cursor/mcp.json,内容如下:
{
"mcpServers": {
"blender": {
"command": "uvx",
"args": [
"mcp-for-blender"
]
}
}
}
在 Windows 上,README 用的是 "command": "cmd" 加 "args": ["/c", "uvx", "mcp-for-blender"]。README 还提供了 Cursor 和 VS Code 的一键安装按钮,以及 Claude Desktop、OpenCode 和 Antigravity 的配置块。它说同一时间只能运行一份服务器,比如用 Cursor 或 Claude Desktop,但不要两个都开。
连接 Blender 插件
快速安装器会替你完成这一步。手动操作如下:
- 运行
uvx mcp-for-blender install-addon。它会把插件作为blender_mcp.py复制到 Blender 的插件文件夹。 - 在 Blender 里打开 Edit → Preferences → Add-ons,启用 Interface: MCP for Blender。如果没出现,重启 Blender,或者点击 Install… 选择复制过去的文件。你也可以从仓库下载
addon.py来安装。 - 在 3D 视口里按 N 打开侧边栏,找到 MCP for Blender 标签页。Blender 打开时插件会自动启动它的服务器。如果没在运行,点击 Start MCP Server。
插件的这个标签页里可以开启可选功能,例如 Poly Haven、Poly Pizza(需要免费 API key)和各种 3D 生成器。
如果智能体连不上:确认 Blender 已打开且插件在运行,并且不要自己在终端里启动 uvx mcp-for-blender(README 的排错表里这么要求)。从 Dock 或开始菜单启动的应用可能找不到 uvx,报 spawn uvx ENOENT。解决办法是把 which uvx(macOS/Linux)或 where uvx(Windows)给出的完整路径作为命令。还不行的话,重启智能体和 Blender。
完整示例:从提示词到 three.js 的低多边形游戏道具
目标:给网页游戏做一个宝箱,体积小、加载快,格式能被 three.js 直接读取。这套流程是我们根据文档写的,没有完整跑过一遍,所以文件大小和具体结果会有差异。
1. 先保存你的 Blender 文件
新建一个 Blender 文件,在智能体开始前先保存(比如 chest.blend)。智能体会直接修改你的文件,README 自己的警告就是务必先保存。
2. 给智能体下提示词
在 Claude Code 或 Codex 里,Blender 已打开并连接:
Use the Blender MCP tools. In the current scene, build a low-poly treasure chest
for a browser game:
- About 1 m wide, 0.6 m deep, 0.7 m tall, sitting on the ground at z = 0,
origin at the bottom centre.
- A box body and a curved lid made from a half-cylinder with 8 segments,
plus metal bands and a lock plate. Keep it under 1,500 triangles.
- Flat-shaded materials using Principled BSDF base colours only
(dark wood, brass), no image textures.
- Apply all modifiers and transforms, join everything into one object named "Chest".
- Check it with the look tool from several angles and fix anything that
overlaps or floats.
- Then select only "Chest" and export it as a GLB to ./public/models/chest.glb.
Show me each script before you run it.
这个提示词里有几个选择对游戏很重要。纯基础色导出最干净,因为 glTF 导出器从 Principled BSDF 节点取基础色,见 Blender 的 glTF 手册。合并成一个物体,在 three.js 里就是一个 mesh。原点放在底部,设置 y = 0 时宝箱就落在地面上。限定三角面数,能防止智能体加细分。
3. 导出这一步
Blender Python 由智能体来写。导出通常以类似下面的调用结尾,用的是 Blender 的 export_scene API 文档里的参数:
import bpy
bpy.ops.export_scene.gltf(
filepath="/path/to/your-game/public/models/chest.glb",
export_format='GLB', # single binary file: mesh, materials and images packed together
use_selection=True, # only the selected "Chest" object
export_apply=True, # apply modifiers on export
export_yup=True, # glTF's +Y up convention, which three.js also uses
)
和智能体运行的每个脚本一样,批准之前先读一遍。检查路径指向你项目里面,并且没有删除或覆盖你在意的文件。
4. 用 glTF-Transform 压缩 GLB
glTF-Transform 是优化 glTF 文件的命令行工具。安装后运行 optimize。下面是它 README 里的命令:
npm install --global @gltf-transform/cli
gltf-transform optimize input.glb output.glb --texture-compress webp
对我们的宝箱:
gltf-transform optimize public/models/chest.glb public/models/chest.opt.glb --texture-compress webp
optimize 默认用 meshopt 压缩几何体(--compress meshopt),把贴图限制在 2048 px 以内,并展平场景图。我们的宝箱没有图片贴图,所以 --texture-compress webp 在这里没有作用,但带贴图的道具建议保留。如果只想压缩几何体,glTF-Transform 还有 gltf-transform meshopt input.glb output.glb --level medium。
5. 在 three.js 里加载
meshopt 压缩过的文件需要 meshopt 解码器。没有它,GLTFLoader 会抛出“setMeshoptDecoder must be called before loading compressed files”。下面的 import 是 three.js 自己的示例里用的:
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
import { MeshoptDecoder } from 'three/addons/libs/meshopt_decoder.module.js';
const loader = new GLTFLoader();
loader.setMeshoptDecoder(MeshoptDecoder);
const gltf = await loader.loadAsync('/models/chest.opt.glb');
const chest = gltf.scene;
chest.position.set(0, 0, -3); // origin is at the bottom, so y = 0 puts it on the floor
scene.add(chest);
Blender 用米做单位,多数 three.js 场景也是,所以宝箱加载后应该大约 1 m 宽。如果它是躺倒的,多半是导出时没开 export_yup。如果是黑的,说明场景需要灯光:加一个 HemisphereLight 或环境贴图。
6. 反复调整
保持 Blender 文件打开,让智能体继续改,比如“让盖子打开 40 度,并做成名为 Lid 的单独物体”或“在里面加一堆金币”。然后重新运行导出和 optimize 命令。让智能体把导出脚本保存在你的项目里,每次就能用同样的设置。
限制和安全
- **它能在 Blender 里运行任何 Python。**README 的警告是:“The
execute_blender_codetool allows running arbitrary Python code in Blender, which can be powerful but potentially dangerous.”Blender 里的 Python 能读写你的用户账号能访问的任何文件。让智能体在运行前先展示脚本,并且自己读一遍。 - 每次使用前先保存文件。同一段警告的结尾是:“ALWAYS save your work before using it.”边做边保存版本(File → Save Incremental)。
- **不需要文件或网络访问时,开启安全模式。**给服务器设置
BLENDER_MCP_SAFE_MODE=1。之后每个脚本运行前都会被检查,直接读写文件、运行其他程序、使用网络,或在脚本结束后继续运行的代码都会被拦截。建模、材质、渲染、保存和导入/导出仍然可用。 - 只在 localhost 上使用。插件的 socket 没有认证,也没有加密。能连到那个端口的人都能在你的 Blender 里运行 Python。不要把它暴露给你不信任的网络。
- 把大任务拆成步骤。README 说复杂操作可能需要拆小,超时靠简化请求来解决。Poly Haven 的下载在 Blender 主线程上运行,所以下载完成前 Blender 会卡住。
- **检查素材许可。**Poly Haven 是 CC0。Poly Pizza 约 69% 是 CC-BY,需要署名。插件会把署名行写到导入的物体上,你也可以用
licence="CC0"搜索。 - **遥测。**默认情况下,服务器会发送一条匿名使用记录:安装 ID、会话 ID、工具名、是否成功、耗时、版本、操作系统和时间戳。只有你主动选择加入,才会收集你的提示词、代码、截图和场景数据。
DISABLE_TELEMETRY=true会把这些全部关掉。
Blender MCP 的替代方案
- Blender Lab 的 Blender MCP:Blender 自己的服务器。它更小,围绕 Python API 文档、场景和文件概要、截图以及运行代码来做,包括针对
.blend文件的后台模式。它需要 Blender 5.1+,采用 GPL-3.0。它的 wiki 里的设置方式是克隆仓库,再用uv --directory .../blender_mcp/mcp run blender-mcp运行。如果你想用官方项目,又不需要素材搜索或 AI 模型生成,就选它。 - Blender Agent Skills:28 个面向 Blender 5.2 LTS+ 的 skill(建模、UV、烘焙、绑定、动画、优化、导出),适用于 Claude Code、Codex、OpenCode、Gemini CLI、Copilot 和 Cursor。MIT。Skill 教智能体怎么做事,MCP 服务器让它能控制 Blender。两者可以一起用。
- blender-game-skills:把概念图做成带绑定、可直接用于游戏的 3D 素材的 Claude Code skill。MIT。
- 现成的模型。常见道具直接用免费模型往往比生成更快。见 Polyfork 的低多边形 GLB。
我们的游戏开发智能体 skill 和 MCP 服务器清单介绍了 Godot、Unity、Unreal 和 three.js 上对应的工具。
常见问题
Blender MCP 免费吗?
免费。MCP for Blender 采用 MIT 许可证,插件免费。它的 Premium 页面说所有功能在免费版都能用,只有 3D 生成要付费。你可以用自己的 API key 接 Meshy、Tripo、Hunyuan3D、Hyper3D Rodin 或 World Labs,也可以买 Premium(2026 年 11 月 21 日起每月 10 美元起)免 key 使用。Blender Lab 的服务器采用 GPL-3.0,也免费。你的 AI 智能体的订阅或 API 费用仍然要另付。
Blender MCP 安全吗?
取决于你让它运行什么代码。智能体在 Blender 里执行 Python,这些 Python 拥有你的用户对文件的访问权限。先保存工作,批准前先读脚本,使用安全模式(BLENDER_MCP_SAFE_MODE=1),并让插件的端口只在 localhost 上。请从官方仓库或项目自己的安装脚本安装,不要用别人转传的副本。
有官方的 Blender MCP 服务器吗?
有。Blender Lab 在 projects.blender.org/lab/blender_mcp 发布了一个,Claude 的连接器目录里以“Blender”之名列出,作者是 Blender Lab。更出名的 MCP for Blender(原名 blender-mcp)是第三方项目,与 Blender Foundation 没有关联。
Blender MCP 能配合 Claude Code 用吗?
可以。运行 claude mcp add blender uvx mcp-for-blender,打开启用了插件的 Blender,再用 claude mcp list 检查。Claude Desktop 则是在 claude_desktop_config.json 里加一段 JSON 来配置。
Blender MCP 能配合 Codex 用吗?
可以。运行 codex mcp add blender -- uvx mcp-for-blender,或者把 [mcp_servers.blender] 加到 ~/.codex/config.toml。README 还提供一个 Codex 插件,可以在聊天旁显示实时的 Blender 视口。
Blender MCP 能配合 ChatGPT 用吗?
README 列出的是桌面端和编程类客户端(Claude Desktop、Claude Code、Codex、Cursor、VS Code、Windsurf、OpenCode、Antigravity),没有 ChatGPT 应用。OpenAI 做这类事用的是 Codex。服务器要连接的是你自己电脑上运行的 Blender,所以需要一个能启动本地 MCP 服务器的客户端。
Blender MCP 的标签页在哪?
在 Blender 的 3D 视口里按 N 打开侧边栏,标签页叫 MCP for Blender。如果没有,在 Edit → Preferences → Add-ons 里启用 Interface: MCP for Blender。
用 Blender MCP 还是 Blender skill?
MCP 服务器让智能体能操作一个运行中的 Blender:创建物体、查看视口、导出。Skill 教智能体 Blender 的工作流程和惯例,不管它之后是通过 MCP 还是在命令行里无界面运行 Blender,都有帮助。做游戏素材时,两者一起用效果不错。MCP 服务器负责建模,Blender Agent Skills 这样的 skill 包负责 UV、优化和导出设置。
来源
2026 年 11 月 21 日核对:mcp-for-blender README、MCP for Blender Premium、Blender Lab blender_mcp及其设置 wiki、Claude Code MCP 文档、Codex MCP 文档、Blender export_scene API、Blender glTF 2.0 手册、glTF-Transform CLI、three.js GLTFLoader。



