BlenderLens

BlenderLens

一款 MCP 服务，可让 AI Agent 在 Blender 中进行建模、贴图和动画制作，从单个物体到完整的动画场景皆可。你可以在自己的 Blender 窗口中观看 Agent 操作，并撤销它的任何操作；也可以让它在没有窗口的后台 Blender 中运行。最终结果是普通的 .blend 文件，或按你需要的格式导出的文件。

AI Agent 通过 BlenderLens 在 Blender 中制作的短动画场景，播放速度为两倍。

功能

连接服务后，只需描述你的需求，Agent 就会在 Blender 中构建场景。使用 BlenderLens，它可以：

• 建模：从基本体、沿路径的管状体、旋转剖面、3D 文本或原始顶点开始，然后挤出、内插、倒角、平分、实体化和细分，或添加任意 Blender 修改器。
• 贴图：创建带有自发光和透明度的 PBR 材质、顶点颜色、UV 展开，以及烘焙颜色、环境光遮蔽、法线和光照贴图。
• 制作动画：为移动、旋转、缩放和形态键设置关键帧，并将它们保存为命名片段。
• 组装场景：放置、设为父级、复制和编组物体，并让物体下落，直到落在下方物体上。
• 查看作品：从任意角度渲染预览，或渲染包含多个视角的视图表，支持着色、黏土或线框风格。
• 检查：测量部件、查找相互穿透的物体，并在你发现问题之前捕捉几何体错误。
• 交付：保存 .blend 文件，或导出为 glTF、FBX、OBJ、STL、PLY 或 USD；导入现有模型；运行你自己的构建脚本。

专为 AI Agent 打造

Agent 已经可以通过编写 Python 来驱动 Blender，但这种方式就像盲人摸象：它看不到结果，无法检查几何体，只能凭猜测操作，而且只有在你打开文件后才能知道出了什么问题。BlenderLens 为它提供了在 Blender 中建模的人所能获得的反馈。

使用原生 Blender Python 的 Agent	使用 BlenderLens 的 Agent
无法查看自己构建的内容	从任意角度渲染预览，或渲染包含多个视角的视图表并查看
编写 bmesh 代码，猜测要编辑哪些面	根据面的朝向选择面并挤出、倒角和内插，同时返回生成的面
无法判断部件是否接触或相互穿透	测量距离和重叠情况，并让物体下落，直到落在下方物体上
留下有问题的几何体、未应用的缩放或位置错误的原点，等你去发现	通过 check_asset 查找这些问题，并列出相关面
从导出器得到 {'FINISHED'}，除此之外一无所知	从磁盘读取每个导出文件，并报告文件中包含的内容
所做的更改难以撤销	每项更改都可通过一次撤销操作撤销

两种运行方式

• 在 Blender 窗口中运行。 安装 BlenderLens 插件并按下 Start，Agent 就会在已打开的 Blender 中工作。你可以实时查看每项更改，在任何时候介入，并按 Ctrl+Z 撤销任何一次调用。
• 在后台运行。 不安装插件时，服务会在首次需要时自行启动 blender --background，并一直运行到服务退出。无需在 Blender 中进行任何设置。

默认情况下，启动插件后，服务会使用你的 Blender 窗口；否则会使用后台 Blender。

要求

	适用范围
Blender 4.2 LTS 或更高版本（已在 4.2 和 5.0 上测试）	所有功能；通过 BLENDER_BIN、PATH 或常见安装目录查找
Python 3.10+，或用于 npx 的 Node.js 18+	运行此服务；它没有依赖项
Blender 中的 BlenderLens 插件	仅在 Blender 窗口中工作时需要

无需 GPU：预览和烘焙使用 Cycles 在 CPU 上渲染。

安装

npx（推荐）。软件包内含此服务，并且需要 PATH 中有 Python 3.10 或更高版本。

{
  "mcpServers": {
    "blenderlens": {
      "command": "npx",
      "args": ["-y", "blenderlens-mcp"],
      "env": { "BLENDER_BIN": "C:\\Program Files\\Blender Foundation\\Blender 5.0\\blender.exe" }
    }
  }
}

pip

pip install blenderlens-mcp

{
  "mcpServers": {
    "blenderlens": { "command": "blenderlens-mcp", "env": { "BLENDER_BIN": "/path/to/blender" } }
  }
}

在 Claude Code 中，这段配置应放在项目的 .mcp.json 中。后台模式只需要这些。

Blender 插件

要在 Blender 窗口中工作，请安装插件：

blenderlens-mcp install-addon       # or: npx -y blenderlens-mcp install-addon; --blender PATH picks the Blender

然后，在 3D 视口中按 N，打开 BlenderLens 选项卡并按 Start。插件仅监听本机，并且只为持有其令牌的服务提供服务；它会将令牌写入一个供服务读取的文件。每个 GitHub 发布版本也会附带此插件的 zip 文件。

Agent 的工作方式

这些工具围绕一个循环构建：

flowchart LR
    B["<b>Build</b><br/>create_object<br/>edit_mesh<br/>set_material"]
    L["<b>Look</b><br/>render_preview<br/>get_object"]
    C["<b>Check</b><br/>check_asset<br/>measure_objects"]
    D["<b>Save</b><br/>save_file<br/>export_file"]

    B --> L --> C --> D
    L -- "not right yet" --> B
    C -- "an issue" --> B

    classDef step fill:#f5f7fa,stroke:#4a6785,stroke-width:1px,color:#1b2733;
    class B,L,C,D step;

1. 构建。 create_object 创建部件，edit_mesh 塑造部件，set_material 为其着色，animate_object 移动部件，而 join_objects 和 set_parent 则用于组装部件。现有构建脚本可通过 run_script 直接运行。
2. 查看。 render_preview 将部件或多个角度的视图渲染为 PNG，供 Agent 查看。 get_object 提供精确的尺寸和计数。
3. 检查。 check_asset 可查找损坏的几何体、未应用的缩放、放置不当的原点、UV 和纹理问题， 以及相互穿透的部件。measure_objects 会说明哪些对象彼此接触。
4. 保存。 save_file 保存 .blend 文件；export_file 和 export_glb 则写入其他格式并读回文件。

工具

单位为米，旋转角度以度为单位，Z 轴朝上。面索引与 get_mesh 列出的索引一致；任何增删面的编辑都会导致索引改变。

会话

工具	描述
get_status	查看服务正在使用哪个 Blender，以及它当前在忙什么；不会启动 Blender。如果出现异常，请从这里开始排查。
open_session	连接到运行插件的 Blender 窗口，或启动后台 Blender；也可选择打开 .blend 文件。
close_session	断开连接。后台 Blender 会退出；窗口则保持打开。存在未保存的更改时会拒绝关闭，除非指定 discard。

检查

工具	描述
get_scene	列出所有对象及其类型、父级、位置、尺寸、计数、材质和修改器。
get_object	查看单个对象的完整信息：变换、边界、修改器应用前后的计数，以及每项修改器设置。
get_mesh	查看对象的面及其索引、中心、法线、朝向和材质：这些索引可供其他工具使用。
list_materials	列出每种材质的属性值及使用该材质的对象。

构建

工具	描述
create_object	创建基本体、沿路径的管状体、旋转剖面、3D 文字或空对象。尺寸会写入网格，因此缩放保持为 1。
create_mesh	根据顶点和面创建网格，用于无法通过基本体创建的形状。
edit_mesh	对按索引或朝向选取的面进行挤出、内插、倒角、二分、实体化、细分等操作。
add_modifier	添加任意 Blender 修改器，设置项使用 Blender 自身的名称。
set_modifier	更改修改器的设置、在堆栈中的位置或可见性。
apply_modifier	将修改器的结果应用到网格中。
remove_modifier	移除修改器而不应用它。
set_material	在对象或选定的面上创建或更新 PBR 材质，并设置自发光、透明度、剔除和图像。
set_vertex_color	将面绘制为颜色属性。
unwrap_uv	展开为 UV 贴图，并报告岛、重叠和纹素密度。
bake_texture	使用 Cycles 将颜色、环境光遮蔽、法线、自发光或完整光照烘焙到 PNG 中，并将其连接到材质。
join_objects	将网格合并为一个部件，每个部分保留其材质。
animate_object	将变换和形状键设置为关键帧，并存入命名片段。
create_collision	为游戏引擎物理创建盒状、凸面或简化后的碰撞代理。

排布

工具	描述
set_transform	设置位置、旋转、缩放或尺寸。使用 drop 时，对象会下落，直到停在下方的物体上。
apply_transform	将旋转和缩放应用到网格，或移动原点，例如移动到底部中心。
set_parent	设置或取消父级，同时保持世界位置。
set_collection	将对象移入集合。
set_object	重命名、隐藏对象或设置自定义属性。
duplicate_object	复制对象及其修改器、材质和子对象。
delete_object	删除对象。

检查与查看

工具	描述
check_asset	按导出时的状态检查对象；也可选择根据三角面 budget 和项目 rules 检查。返回 passed 以及每个问题涉及的面。不会修改任何内容。
measure_objects	测量部件之间的距离、它们是否接触、重叠或彼此包含，或向场景中投射射线。
render_preview	从命名视角或任意角度生成带边框的 PNG，也可在一张图像中生成多个视角；提供着色、黏土、线框或按部件着色样式；可显示周围对象以提供上下文、隐藏相机视角中的对象以制作剖切效果，并提供固定宽度的正交视图。场景会保持原样。

文件

工具	描述
save_file	保存 .blend 文件或检查点副本。
open_file	打开 .blend 文件。
create_file	新建一个空文件。
import_file	导入 glTF、OBJ、FBX、STL 或 PLY 文件，或从 .blend 文件追加对象。
export_file	写出 FBX、OBJ、STL、PLY 或 USD 文件，并重新读取。
export_glb	写出 .glb（二进制 glTF）文件并重新读取，同时警告 Godot 或 three.js 会如何处理它（见下文）。

Python 与撤销

工具	描述
run_python	在 Blender 内运行 Python，以处理任何工具无法涵盖的操作。
run_script	运行构建脚本文件，并使其辅助模块可供导入。
undo_change	逐次撤销更改场景的调用，每次撤销一步。

导出 glTF

export_glb 会写入一个 .glb，然后打开写入的文件并报告其中的实际内容：节点树、三角形数量、材质，以及绘制调用和纹理内存的估算值。它会警告哪些内容在导出过程中丢失，例如不在文件中的对象、未生成网格就写入的元球、应用修改器后丢弃的形状键、缺少所需 UV 的纹理，以及缺少切线的法线贴图。

它的 target 指明要加载该文件的引擎，也决定会出现哪些警告：godot、threejs 或 generic（默认值），后者会同时提供以下两类警告：

• Godot：它会读取为导入提示的名称（Rock_col 会生成一个碰撞体）、因名称而循环播放的动画、会重命名的节点、无法加载的扩展，以及 Godot 4.7.0 到 4.7.2 在网格的第一个图元上会忽略的顶点颜色。由于 Godot 无法导入 Draco 压缩，因此会拒绝这种压缩。
• three.js：GLTFLoader 无法加载的扩展，或只能在应用设置解码器后才能加载的扩展。create_collision 创建的碰撞代理不会包含在内，因为 three.js 会绘制它们。

项目规则

当一组模型必须遵循相同约定时，check_asset 可以根据三角形预算和你自己的规则逐一检查每个模型；规则可内联提供，也可通过 rules_file 提供。规则是一个 JSON 对象，每个键均为可选项：

键	失败条件
required	缺少指定名称的对象或 "Parent/Child" 路径
single_root	资源的根对象数量不为 1
retired	对象或材质使用了项目不再采用的名称
palette, palette_only	材质颜色或数值与调色板不同，或材质不在调色板中
extras	缺少自定义属性，或其类型不正确
size	对象尺寸超出以米为单位的范围
origin_at_base	原点不在对象底部
budget	资源或指定部件的三角形数量超出限制
apart	两个不得接触的部件相互穿透

名称也可以是一个模式："re:<regular expression>"。examples/rules.json 是一套完整的规则集，而 examples/build_lantern.py 则通过该服务从头到尾构建、检查并导出一个道具。

这些检查也可以在没有 Agent 的情况下运行，例如在构建流水线中运行。检查 .glb 时无需 Blender；检查 .blend 时会在后台 Blender 中打开文件。--target 会添加对应引擎的警告，--json 会输出完整结果。模型通过检查时命令退出码为 0，未通过时为 1，无法检查时为 2。

blenderlens-mcp check lantern.glb --budget 2000 --rules rules.json

错误

当工具拒绝调用时，不会进行任何更改，并会返回 error（发生了什么问题）、exit（每种错误对应的固定编号）、kind 和 hint（如何处理）。

Exit	Kind	含义
1	blender_error	Blender 在运行调用时发生错误
2	not_found	调用所需的对象、材质、文件或几何体不存在
3	bad_argument	参数的值无法被 Blender 使用
4	python_error	run_python 或 run_script 运行的代码引发了异常
5	unsaved_changes	打开的文件有未保存的更改；请先保存，或传入 discard
6	blender_missing	未找到 Blender 可执行文件
7	not_connected	没有 BlenderLens 插件响应
8	connection_lost	调用期间 Blender 退出或崩溃，或插件已停止
9	start_failed	后台 Blender 未能启动
10	version_mismatch	插件使用的是另一个协议版本；请重新安装
11	token_mismatch	插件拒绝了服务端的令牌
12	busy	Blender 仍在处理先前的调用
13	not_allowed	Python 已关闭，或路径位于 BLENDERLENS_ALLOWED_DIRS 之外
70	internal_error	BlenderLens 本身发生故障
124	deadline	Blender 未能及时响应，可能仍在处理中

限制

• Python 不受限制。 run_python 和 run_script 可以在 Blender 中执行 Python 能做的任何事，包括退出 Blender。请设置 BLENDERLENS_ALLOW_PYTHON=0，或在插件中关闭 Allow Python from the agent（如适用）。
• drop 只会在顶点处寻找支撑。 如果唯一的接触方式是边与边接触，例如一根杆横跨在另一根杆上，就会漏掉该支撑，物体会继续下落。
• BlenderLens 无法看到节点组内部的 Principled BSDF，因此不会更改该材质的值。
• 在 Blender 窗口中，预览会将文件标记为已更改，因为每当设置渲染引擎时（即使设回相同的引擎），Blender 都会这样做。
• Blender 的 glTF 导出器会将 metaball 导出为空节点。 check_asset 会将 metaball 报告为错误，export_glb 则会对其发出警告。

架构

flowchart TD
    Agent["AI Agent"]
    BL["<b>BlenderLens</b><br/>MCP server<br/>Python 3.10+<br/>no dependencies"]

    Agent <-- "stdio, JSON-RPC 2.0" --> BL

    BL -- "TCP 9877<br/>with its token" --> Window
    BL -- "starts and owns" --> Background

    Window["<b>Blender window</b><br/>add-on started<br/><i>you watch, and can undo</i>"]
    Background["<b>blender --background</b><br/>no window<br/><i>lives as long as the server</i>"]

    classDef svc fill:#eef4fb,stroke:#4a6785,stroke-width:1px,color:#1b2733;
    classDef blender fill:#f3f0fb,stroke:#6b5b95,stroke-width:1px,color:#1b2733;
    class Agent,BL svc;
    class Window,Background blender;

两种方式都会在 Blender 主线程上运行相同的命令代码；网格操作通过 bmesh 完成，因此无论是否打开窗口，行为都相同。每次更改场景的调用都会成为一个撤销步骤。MCP 协议和与 Blender 的连接基于 Python 标准库构建，因此该软件包没有运行时依赖项。 docs/architecture.md介绍了各模块，docs/decisions/记录了每个部分采用当前设计的原因。

配置

变量	默认值	描述
BLENDER_BIN	auto	Blender 可执行文件，用于后台会话、check 和 install-addon
BLENDERLENS_MODE	auto	auto（启动其插件时使用窗口，否则使用后台）、live（仅使用窗口）或 background
BLENDERLENS_HOST	127.0.0.1	服务连接插件的位置：localhost 或回环 IPv4 地址
BLENDERLENS_PORT	9877	插件端口，在其首选项中设置
BLENDERLENS_TOKEN	来自插件文件	覆盖插件为服务写入的令牌
BLENDERLENS_TIMEOUT	120	单次调用的等待秒数；render_preview、bake_texture、run_python 和 run_script 也接受 timeout
BLENDERLENS_START_TIMEOUT	90	等待后台 Blender 启动的秒数
BLENDERLENS_RENDER_DIR	临时文件夹	未提供 path 时预览文件的存放位置；默认文件夹中的文件会保留 7 天
BLENDERLENS_ALLOW_PYTHON	1	0 会移除 run_python 和 run_script
BLENDERLENS_ALLOWED_DIRS	未设置	工具收到的所有路径都必须位于这些文件夹内；Windows 上用 ; 分隔，其他系统上用 : 分隔
BLENDERLENS_RUNTIME_DIR	每位用户独立	插件令牌文件和未保存后台工作的恢复副本的存放位置

许可证

Apache License 2.0 — 请参阅 LICENSE 和 NOTICE。BlenderLens 与 Blender 基金会无关， 也未获得其认可。