three.ws Blender

@three-ws/blender-mcp

让任何 AI Agent 都能使用你机器上的 Blender。无头运行，无需 GUI，也无需安装插件。

---

一个 Model Context Protocol 服务，通过 stdio 为 AI 助手提供真实的 Blender。检查 3D 文件，在 GLB、glTF、FBX、OBJ、STL、PLY、Collada、Alembic、USD 和 .blend 之间转换，渲染自动取景、自动布光的预览，并以内嵌形式返回，让助手能够查看；对场景运行 bpy 脚本；还可以通过免费的 three.ws Forge 通道，根据文本提示词生成模型。

Blender 以后台模式运行（blender -b），每次调用启动一个进程。因此，它可以在服务器、CI 和容器中运行，无需显示器、无需保持 GUI 会话，也无需先在 Blender 中安装插件。一切都是真实的：每个工具都会驱动机器上安装的 Blender，而 blender_forge_import 会调用实时公开的 three.ws 生成流水线。

要求

• Node.js 20+
• Blender 3.0 或更高版本，需本地安装。下载，或通过包管理器安装。如果它不在 PATH 中，请将 BLENDER_PATH 设置为可执行文件的路径（macOS 上为 /Applications/Blender.app/Contents/MacOS/Blender）。

如果出现任何异常，请先调用 blender_info：它会报告此构建支持的可执行文件、版本、渲染引擎和文件格式的准确信息。

安装

npm install @three-ws/blender-mcp

或者使用 npx 运行（无需安装）：

npx -y @three-ws/blender-mcp

Claude Code

claude mcp add blender -- npx -y @three-ws/blender-mcp

Claude Desktop / Cursor

将以下内容粘贴到 MCP 配置中（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 上为 %APPDATA%\Claude\claude_desktop_config.json）：

{
	"mcpServers": {
		"blender": {
			"command": "npx",
			"args": ["-y", "@three-ws/blender-mcp"]
		}
	}
}

如果 Blender 不在 PATH 中，请添加 "env": { "BLENDER_PATH": "/path/to/blender" }。

工具

工具	功能
blender_info	报告当前驱动的 Blender 信息：路径、版本、捆绑的 Python、可用的渲染引擎，以及此构建实际支持的导入/导出格式。只读。
blender_scene_info	打开 3D 文件并描述其内容：对象的类型、父级、尺寸和修改器；求值后的三角形数和顶点数；材质；纹理清单（包含每张图像的分辨率和字节大小）；骨架骨骼名称；带帧范围的动画动作；世界空间边界。只读。
blender_convert	根据文件扩展名导入一种格式并导出为另一种格式。默认应用修改器，并可烘焙统一的单位缩放。具体格式列表取决于构建版本（某些 Linux 软件包未附带 USD、Collada 或 Alembic 支持）；blender_info 会报告你实际拥有的格式支持。
blender_optimize	一次调用即可完成交付前处理：将模型抽取到指定三角形预算、缩小过大的纹理、清除未引用的数据块，并使用 meshopt 或 Draco 压缩网格数据流。报告处理前后的三角形数、纹理字节数和文件大小。
blender_render	渲染静态 PNG 并以内嵌形式返回，因此助手只需一次调用就能看到模型，即使无法访问文件系统也不例外。要求生成多个视角时，它会在同一次启动中绕模型旋转，呈现每个角度。如果文件没有相机，就会创建一台相机，并根据模型的包围球调整取景；如果没有灯光，则会添加主光源和有照明的世界环境。场景已有相机和灯光时，则按原有设置渲染。
blender_run_python	对场景运行 bpy 脚本，可选先打开文件，并在之后导出结果。这是其他工具无法覆盖时的备用途径。
blender_forge_import	通过公开的 three.ws Forge 工作流，根据文本提示词或参考图像生成模型并导入 Blender；如果输出要求其他格式，则会在导入过程中转换。默认通道免费。

示例

先描述文件，再对其进行操作：

> What is in ~/assets/character.fbx?

blender_scene_info { "input": "~/assets/character.fbx" }
→ 4 meshes, 41,208 triangles, 1 armature (67 bones), 3 actions, bounds 1.78m tall

让模型达到可交付状态，并查看处理代价：

blender_optimize { "input": "character.glb", "output": "character-web.glb", "max_triangles": 30000, "max_texture_px": 1024 }
→ 4.1 MB to 780 KB (81% saved): 96,412 to 30,000 triangles, textures 2048 to 1024, meshopt compressed

同时从四个侧面查看模型：

blender_render { "input": "character-web.glb", "views": 4 }

将客户提供的 FBX 转换为适合 Web 的 GLB，单位为米：

blender_convert { "input": "character.fbx", "output": "character.glb", "scale": 0.01 }

查看刚刚创建的模型：

blender_render { "input": "character.glb", "output": "preview.png", "samples": 64 }

将三角形数减半，并在一次调用中导出：

blender_run_python {
  "input": "character.glb",
  "output": "character-lod1.glb",
  "code": "import bpy\nfor obj in bpy.data.objects:\n    if obj.type == 'MESH':\n        obj.modifiers.new('Decimate', 'DECIMATE').ratio = 0.5\nresult = {'meshes': len([o for o in bpy.data.objects if o.type == 'MESH'])}"
}

生成资产并将其作为 .blend 打开：

blender_forge_import { "prompt": "a weathered brass diving helmet", "output": "helmet.blend" }

或者根据参考图像重建模型：

blender_forge_import { "image": "./reference.png", "prompt": "a brass diving helmet", "output": "helmet.glb" }

压缩的 glTF

在 Blender 打开 Meshopt 和 Draco 压缩的资产之前，会在进程内自动解码，无需安装外部二进制文件。

这可不是可有可无的功能。Blender 的 glTF 导入器不支持解码 EXT_meshopt_compression。gltfpack 会生成这种压缩格式，大多数 three.ws Avatar 也以这种格式交付；如果直接将这类文件交给导入器，它会直接失败，并提示 "Extension EXT_meshopt_compression is not available on this addon version"。Draco 名义上受支持，但仅限附带 libextern_draco 的构建版本，而有些 Linux 发行版软件包并未附带它。所有接受 input 的工具都会采用相同的解码流程，响应中的 decoded_compression 会注明解码的压缩格式。文件本身不会被修改：解码后的副本存放在任务的临时目录中，并会随任务一起删除。

调用的工作方式

每次工具调用都会启动 blender -b --factory-startup --python src/py/runner.py -- <job.json> <result.json>，然后退出。有三点值得了解：

• --factory-startup 会排除你保存的偏好设置和第三方插件，因此转换在任何机器上都会生成相同的文件。
• 运行器会将负载写入文件，而不是 stdout。 Blender 会在 stdout 中输出进度、插件信息和渲染统计数据，从这些输出中找出负载只能靠猜。因此，结果文件缺失就意味着 Blender 已崩溃，错误中会附带说明原因的日志尾部内容。
• 每次调用启动一个进程。 崩溃的任务不会影响下一个任务，调用之间也不会有进程驻留。

失败时会返回结构化的工具错误（input_not_found、format_unsupported、engine_unavailable、timeout、blender_not_found、blender_unusable、blender_crashed），每个错误都附有说明如何处理的信息。blender_not_found 表示不存在可用候选项；blender_unusable 表示存在候选项，但无法运行，并附带各候选项的诊断信息，因为在负载较高的机器上，探测失败可能只是暂时的；如果让你安装已经装好的软件，那就不是正确的处理方式。

环境变量

变量	默认值	用途
BLENDER_PATH	在 PATH 和平台标准安装位置中发现	Blender 可执行文件的绝对路径。
BLENDER_MCP_TIMEOUT_MS	300000	单个 Blender 任务的最长运行时间。
BLENDER_MCP_WORKDIR	<tmpdir>/three-ws-blender-mcp	调用工具时未指定输出路径的输出文件保存位置。
BLENDER_MCP_ALLOW_PYTHON	1	设置为 0，即可将 blender_run_python 从已公布的工具列表中完全移除。
BLENDER_MCP_MAX_CONCURRENCY	2	允许同时运行的 Blender 进程数。后续调用会排队，而不是争抢内存。
BLENDER_MCP_INLINE_IMAGE_PX	768	内嵌返回的渲染副本的最长边。全分辨率 PNG 始终会写入磁盘。
BLENDER_MCP_INLINE_IMAGE_BYTES	1500000	超过此大小后，图像会留在磁盘上，响应中也会说明这一点。
THREE_WS_BASE	https://three.ws	为 blender_forge_import 提供支持的部署地址。
THREE_WS_FORGE_TIMEOUT_MS	600000	单次文本转 3D 生成的最长运行时间。
THREE_WS_FORGE_PROVIDER_KEY	未设置	自带密钥几何生成通道所需的 Meshy/Tripo 密钥。默认图像通道免费且无需密钥。

安全性

blender_run_python 会在 Blender 中执行调用方提供的 Python 代码，权限与此服务相同：它可以读写本地文件系统。这正是此工具的用途，并且它标注了 destructiveHint: true，以便客户端在运行前征求确认。对于无人值守或共享部署，请设置 BLENDER_MCP_ALLOW_PYTHON=0，这样就不会公布此工具。

其余操作都在本地进行。只有 blender_forge_import 会访问网络，并且只会访问 THREE_WS_BASE 指定的 three.ws 部署。

开发

node src/index.js                        # run the server over stdio
npm test                                 # offline invariants + real-Blender integration
npm run inspect                          # open the MCP Inspector against it

test/registration.test.mjs 可离线运行，即使未安装 Blender 也能通过。test/blender-session.test.mjs 会通过真实的 MCP stdio 会话，使用本地 Blender 驱动服务，并由 Blender 自行构建测试夹具；如果未安装 Blender，则会正常跳过。

相关内容

• integrations/blender/ 是面向艺术创作者的配套项目：一个带侧边栏面板的 Blender 插件，可在图形界面中生成 three.ws 模型。本软件包面向 Agent。
• @three-ws/scene-mcp 可根据一句描述构建完整的 3D 世界。
• three.ws 是 Forge 工作流背后的平台。

许可证

Apache-2.0