Blender MCP Server Connection Skill#

Connect to and control a running Blender instance via the official Blender MCP Server.

通过官方 Blender MCP Server 连接和控制运行中的 Blender 实例。

Version support: Blender 5.1+（官方 add-on 的硬性要求）, 5.2.x LTS (current 5.2.2), and 5.3 Beta（Python API 自 Beta 起稳定；RC 2026-11-04 → 发布 2026-11-10）— API compatibility notes included below Last verified: 2026-10-13（每日快扫：官方 issue/PR 首次实证取证（Gitea REST API 绕开 HTML 403）；add-on 仍 v1.0.3（最新发布 2026-09-11，无 v1.0.4）；排障表补 7 条工具行为坑；完整清单见 knowledge/blender-mcp/research-tracker.md）

---

⚠️ Security Warning / 安全警告#

English: This skill provides full access to Blender's Python API ( bpy) through the MCP channel. Code executed via execute_blender_code can:

• Read, modify, or delete files on your system
• Execute arbitrary Python code (including network requests)
• Alter or corrupt your Blender project data

Always review code before execution. Keep backups of important .blend files.

中文： 此技能通过 MCP 通道提供对 Blender Python API ( bpy) 的完全访问。通过 execute_blender_code 执行的代码可以：

• 读取、修改或删除系统上的文件
• 执行任意 Python 代码（包括网络请求）
• 更改或损坏 Blender 项目数据

执行前请始终审查代码。保持重要 .blend 文件的备份。

---

Architecture Overview#

text

┌─────────────┐     TCP Socket      ┌──────────────────     MCP Protocol     ┌──────────────
│  LLM Client │ ◄─────────────────► │  MCP Server      │ ◄──────────────────► │   Blender    │
│  (OpenClaw) │    stdio / HTTP     │  (Python process) │    port 9876         │   (Addon)    │
└─────────────┘                     └──────────────────┘                      └──────────────

Two-component architecture:

1. Blender Addon — runs inside Blender, provides a TCP Socket Server (default localhost:9876)
2. MCP Server — standalone Python process that bridges the LLM client and the Blender Addon

---

Installation#

1. Install the Blender Addon#

Requirements (official): Blender 5.1 or newer（官方 Lab 页原文）；官方 add-on 当前版本 v1.0.3（2026-10-11 复核，与 10-09 / 10-10 一致）。

Option A: From ZIP (official release / 官方发布)

1. Download addon ZIP: https://projects.blender.org/lab/blender_mcp/releases/download/v1.0.3/mcp-1.0.3.zip （或从官方落地页 https://www.blender.org/lab/mcp-server/ 取最新链接）
2. Blender → Edit → Preferences → Add-ons → Install from Disk
3. Enable the MCP addon (listed as MCP, maintained by Blender Lab)
4. Confirm Host/Port in addon settings (default localhost:9876)
5. Optional: Enable "Auto Start" — ⚠️ 只在 Blender 启动时 触发；刚装完状态仍是 "Server is stopped"，需手动点一次 Start MCP Bridge Server

Option B: Drag & Drop

• Drag the install link/ZIP into the Blender window twice: first drop adds the Blender Lab repository, second installs the addon
• 好处：之后能收到 add-on 更新通知

Option C: From Source

• Source code locations: mcp/blmcp/ and addon/blender_mcp_addon/

Option D: Quick Install via uvx (Simplest / 最简单)

bash

# Install uv first (safe method / 安全方法)
# Download installer and verify before running / 下载并验证后再运行
# Windows: Invoke-WebRequest -Uri "https://astral.sh/uv/install.ps1" -OutFile "$env:TEMP\uv-install.ps1"
#          Review the script, then: powershell -ExecutionPolicy Bypass -File "$env:TEMP\uv-install.ps1"
# Mac/Linux: curl -LsSf https://astral.sh/uv/install.sh -o install.sh
#            Review the script, then: sh install.sh

# Start MCP server with pinned version (auto-downloads dependencies)
uvx blender-mcp@1.0.0

⚠️ 别把两个版本号搞混（真实高频困惑）：

• Blender add-on（官方 Lab 发布，装在 Blender 里）：当前 v1.0.3 —— 见上面 Option A 链接
• MCP Server 包（ uvx/ pip 装的 Python 进程）：本文档 pin 在 1.0.0（PyPI 包 blender-mcp） 两者版本号各自独立；排障时先确认「哪一半」出问题。

2. Start the Blender MCP Server#

bash

# Install dependencies with pinned versions
cd path/to/blender_mcp
pip install mcp==1.8.0 pyyaml==6.0.2 starlette==0.45.0

# Start MCP Server (stdio mode)
python -m blmcp --transport stdio

# Or HTTP mode (default 127.0.0.1:8000)
python -m blmcp --transport http --host 127.0.0.1 --port 8000

3. Configure mcporter#

bash

# Add Blender MCP Server config
mcporter config add blender-mcp --transport stdio --command "python -m blmcp --transport stdio"

# Or use HTTP mode
mcporter config add blender-mcp --transport http --url "http://127.0.0.1:8000"

# Verify connection
mcporter list blender-mcp --schema

---

Usage#

Method 1: Via mcporter (recommended)#

bash

# List all available tools
mcporter list blender-mcp --schema

# Call a specific tool
mcporter call blender-mcp.execute_blender_code code='import bpy; result = {"objects": [o.name for o in bpy.data.objects]}'

mcporter call blender-mcp.get_objects_summary
mcporter call blender-mcp.get_object_detail_summary object_name="Cube"

# Search API docs
mcporter call blender-mcp.search_api_docs query="bpy.ops.object.delete"

# Search user manual
mcporter call blender-mcp.search_manual_docs query="Geometry Nodes"

# Screenshot
mcporter call blender-mcp.get_screenshot_of_window_as_image

# Render viewport
mcporter call blender-mcp.render_viewport_to_path output_path="C:\\render.png"

Method 2: Direct TCP Socket to Blender Addon (lightweight)#

⚠️ Warning: This mode sends caller-supplied code directly to Blender with no guardrails. Review code before execution.

python

import socket
import json

def send_to_blender(code: str, host="localhost", port=9876, timeout=30.0) -> dict:
    """Send Python code directly to Blender Addon for execution."""
    request = json.dumps({
        "type": "execute",
        "code": code,
        "strict_json": False,
    }) + "\0"

    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
        sock.settimeout(timeout)
        sock.connect((host, port))
        sock.sendall(request.encode("utf-8"))

        buf = bytearray()
        while True:
            chunk = sock.recv(65536)
            if not chunk:
                break
            buf.extend(chunk)
            if b"\0" in buf:
                break

    line, _, _ = buf.partition(b"\0")
    return json.loads(line.decode("utf-8"))

# Example: get all object names in the scene
response = send_to_blender(
    'import bpy\nresult = {"objects": [o.name for o in bpy.data.objects]}'
)
print(response)
# {"status": "ok", "result": {"objects": ["Cube", "Camera", "Light"]}}

Method 3: Blender Background Mode (headless rendering / batch)#

bash

# Start Blender background MCP Server
blender --background myscene.blend --command blender_mcp --host localhost --port 9876

# Or execute code via CLI
blender --background myscene.blend --python-expr "
import bpy
# your code
result = {'count': len(bpy.data.objects)}
print('__BLMCP_RESULT__' + str(result))
"

---

Built-in Tools (20 total)#

Core#

ToolDescriptionParamsexecute_blender_codeExecute arbitrary Python code (full bpy access)code: str``execute_blender_code_for_cliExecute code in a background Blender processblend_file: str, code: str

Scene Analysis#

ToolDescriptionParamsget_objects_summaryGet scene object hierarchy and basic infononeget_object_detail_summaryGet detailed info for a specific objectobject_name: str``get_blendfile_summary_datablocksAnalyze .blend file data-blocksblend_file: str``get_blendfile_summary_missing_filesCheck for missing external file referencesblend_file: str``get_blendfile_summary_of_linked_librariesList linked external librariesblend_file: str``get_blendfile_summary_path_infoAnalyze .blend file path informationblend_file: str``get_blendfile_summary_usage_guessGuess the purpose of a .blend fileblend_file: str

Screenshots & Rendering#

ToolDescriptionParamsget_screenshot_of_window_as_imageCapture Blender window screenshotnoneget_screenshot_of_area_as_imageCapture specific area screenshotarea_type: str``get_screenshot_of_window_as_jsonGet window layout as JSON descriptionnonerender_viewport_to_pathRender viewport to fileoutput_path: str``render_thumbnail_to_pathRender thumbnail to fileoutput_path: str

Navigation#

ToolDescriptionParamsjump_to_tab_by_nameJump to a named editor tabtab_name: str``jump_to_tab_by_space_typeJump to a space typespace_type: str``jump_to_view3d_object_by_nameFocus on an object in 3D Viewobject_name: str``jump_to_view3d_object_data_by_nameFocus on object data in 3D Viewdata_name: str

Documentation Search#

ToolDescriptionParamssearch_api_docsSearch Blender Python API docsquery: str``search_manual_docsSearch Blender user manualquery: str``get_python_api_docsGet Python API docsquery: str

---

Communication Protocol#

TCP Socket Protocol#

Request format (null-byte delimited JSON):

json

{"type": "execute", "code": "import bpy\nresult = {'key': 'value'}", "strict_json": false}\0

Response format:

json

// Success
{"status": "ok", "result": {"key": "value"}, "stdout": "", "stderr": ""}\0

// Error
{"status": "error", "message": "Traceback...", "stdout": "", "stderr": ""}\0

Code Execution Conventions#

• Assign return value to the result variable (must be a dict)
• strict_json=True: strict JSON serialization; non-serializable values will error
• strict_json=False: uses repr() as fallback for non-JSON values
• Supports deferred responses: return a check_is_finished callable for long-running tasks

Example: Get Object Info#

python

import bpy
obj = bpy.data.objects.get("Cube")
if obj:
    result = {
        "name": obj.name,
        "type": obj.type,
        "location": list(obj.location),
        "vertices": len(obj.data.vertices) if obj.type == "MESH" else 0,
    }
else:
    result = {"error": "Object not found"}

Example: Create an Object#

python

import bpy
bpy.ops.mesh.primitive_torus_add(
    align='WORLD',
    location=(0, 0, 0),
    major_radius=1.0,
    minor_radius=0.3,
)
result = {"status": "created", "name": bpy.context.active_object.name}

---

Environment Variables#

VariableDefaultDescriptionBLENDER_MCP_HOST``localhostBlender Addon host addressBLENDER_MCP_PORT``9876Blender Addon portBLENDER_PATH``blenderPath to Blender executableDISABLE_TELEMETRY``falseSet to true to disable anonymous usage telemetry. English: Anonymous telemetry may be collected by default. Set to true to opt out. 中文： 默认情况下可能会收集匿名遥测数据。设置为 true 可退出。

---

Security Notes#

⚠️ Official security warning: The MCP Server executes LLM-generated code with no sandboxing.

Built-in weak sandbox ( WeakSandboxForLLM):

• Blocks sys.exit() calls
• Blocks dangerous operators: wm.quit_blender, wm.read_factory_settings, wm.read_factory_userpref, wm.read_userpref

Security Best Practices#

1. Keep server local only — Always use localhost / 127.0.0.1; never bind to 0.0.0.0
2. Review code before execution — Prefer scoped built-in tools over raw execute_blender_code
3. Protect your projects — Keep backups of important .blend files
4. Verify external dependencies — Download addon only from official Blender Lab sources

---

Troubleshooting#

ErrorCauseSolutionConnectionRefusedErrorBlender not running or Addon not startedStart Blender, enable MCP Addon, click "Start Server"ConnectionRefusedError（Blender 开着也没反应）Auto Start 只在 Blender 启动时触发 —— 刚装完 add-on 时状态仍是 "Server is stopped"手动点一次 Start MCP Bridge Server（之后 Auto Start 才会生效）端口被占 / 连上却不是自己的 Blender两个 MCP add-on 不能同时启用（官方 Lab add-on 与社区 blender-mcp 都监听 9876）只留一个：Preferences → Add-ons 里禁用另一个；或改端口并同步 BLENDER_MCP_PORT``Online access must be enabled in the system preferencesBlender 的全局联网开关（官方 add-on 遵守该开关）Preferences → System → Network → Allow Online Access装完在 Add-ons 里找不到拖拽安装 需要拖两次（第一次只加了 Blender Lab 仓库）再拖一次；或改用 Install from DiskConnectionError: Empty responseNetwork timeout or Addon crashedCheck Blender console output, verify portresult is not JSON-serializableReturned a Blender objectUse strict_json=False or manually convert to dictBlender executable not foundBlender command not foundSet BLENDER_PATH environment variableDeferred responses not supportedBackground mode doesn't support deferred responsesUse synchronous code or switch to GUI mode***_for_cli 工具在 Windows + stdio 下 120s 超时挂死**run_blender_cli() 调 subprocess.run() 未传 stdin → 子进程继承 MCP 的 stdio 管道，Windows 上死锁（官方 issue #58 / #60，修复 PR #48 未合并）仍有问题：给该处补 stdin=subprocess.DEVNULL（本地打补丁），或改用非 *_for_cli 的交互工具NameError: name 'bpy' is not defined / 上次的变量不见了**execute_blender_code 每次调用都是全新 Python 命名空间**（ bpy 不预导入、局部变量不跨调用保留；官方 issue #55/#53）每次调用 都写 import bpy；需要跨调用状态就显式写回 bpy 数据或文件get_objects_summary 把上下文撑爆输出随场景复杂度递归增长（1670 对象 ≈ 904 KB ≈ 15.5k+ tokens；官方 issue #54）大场景先用更轻的检查方式；必要时按集合分批查询缩略图 / 渲染产物 不是 想要的分辨率或不在指定路径render_thumbnail_to_path 交互模式会用原分辨率渲染（issue #46/ #61）；两个 *_to_path 工具 只取文件名的 basename，实际写进 MCP 临时目录（issue #53）用工具返回的 filepath 读产物；要确定的分辨率就自己在 execute_blender_code 里设渲染参数并阻塞式渲染get_python_api_docs 查成员文档查不到（ bpy.types.Object.location）成员解析需要 重复类名（官方 issue #62，2026-10-10）用 bpy.types.Object.Object.location； bpy.ops.* 和整类查询正常macOS 上 .mcpb 装不上（"Operation not permitted"）Claude Desktop 的 .mcpb 安装助手与 uv cache 权限冲突（官方 issue #57）macOS 走 add-on + uvx 路线，别依赖 .mcpbWindows 上 blender-mcp.exe 被拦（ os error 4551）Smart App Control / VerifiedAndReputable 策略 拦截无签名启动器（官方 issue #56）用官方 add-on 通道；或临时关闭 SAC（企业环境另说）

查官方动态的正确姿势（2026-10-13 起，绕开 HTML 403）： projects.blender.org 的 网页 长期 403，但 同一站点的 Gitea REST API 可用：

bash

# 仓库 / 发布 / issue / PR（实测 2026-10-13 全部 200）
https://projects.blender.org/api/v1/repos/lab/blender_mcp
https://projects.blender.org/api/v1/repos/lab/blender_mcp/releases?limit=10
https://projects.blender.org/api/v1/repos/lab/blender_mcp/issues?state=open&sort=recentupdate&limit=20
https://projects.blender.org/api/v1/repos/lab/blender_mcp/pulls?state=open&limit=10

官方落地页 https://www.blender.org/lab/mcp-server/ 一般可访问（给 add-on 版本号与安装要求）。 ⚠️ 不要 用搜索摘要代替官方源：本工作区曾据此写下 不存在的 issue 号（#344/#345/#348 实测 404），已作废。

---

Blender 5.1 API Compatibility Notes#

Action Layered Structure (Breaking Change)#

In Blender 5.1, Action.fcurves was removed. The new layered animation system uses:

python

# ❌ Old (5.0 and earlier)
fcurves = action.fcurves

# ✅ Blender 5.1+
fcurves = action.layers[0].strips[0].channelbags[0].fcurves

Brush API: use_* → stroke_method Enum#

python

# ❌ Old (5.0)
brush.use_airbrush = True

# ✅ 5.1+
brush.stroke_method = 'AIRBRUSH'  # Options: AIRBRUSH, SPACE, ANCHORED, LINE, CURVE, DRAG_DOT

VSE Time Property Renames#

Old (5.0)New (5.1)frame_final_duration``duration``frame_final_start``left_handle``frame_final_end``right_handle``frame_duration``content_duration

Principled BSDF Input Renames#

Old (5.0)New (5.1)inputs['Transmission']``inputs['Transmission Weight']``inputs['Emission']``inputs['Emission Color'] + inputs['Emission Strength']

Other 5.1 Changes#

• sculpt.sample_color → paint.sample_color
• bpy.app.cachedir — new standard cache directory
• bpy.app.handlers.exit_pre — new exit handler
• Python 3.13 runtime

---

Blender 5.2 LTS Compatibility Notes (Beta)#

Blender 5.2 LTS entered Beta on 2026-06-03. API is frozen; RC expected 2026-07-08, release 2026-07-14.

🔴 Breaking Changes (12 total — all Beta confirmed)#

1. Geometry Nodes Modifier API Rewrite

python

# ❌ 5.1 and earlier
modifier["SocketName"] = 5.0
modifier["SocketName_use_attribute"] = True
modifier["SocketName_attribute_name"] = "some_input"

# ✅ 5.2+
modifier.properties.inputs.SocketName.value = 5.0
modifier.properties.inputs.SocketName.type = "ATTRIBUTE"
modifier.properties.inputs.SocketName.attribute_name = "some_input"
modifier.properties.outputs.SocketName.attribute_name = "some_output"

# ✅ Compatible pattern
import bpy
if bpy.app.version >= (5, 2, 0):
    val = modifier.properties.inputs.SocketName.value
else:
    val = modifier["SocketName"]

2. Principled BSDF Node Renamed

• Transmission → Transmission Weight
• Already applies from 5.1; ensure plugin references match

3. paint.eraser_brush API Removed

• No longer needs manual setting; last eraser brush auto-activates

4. Automasking → MeshAutomaskingSettings (17 properties migrated)

python

# ❌ Old
brush.use_automasking_topology = True
brush.automasking_cavity_factor = 0.5

# ✅ 5.2+
brush.mesh_automasking_settings.use_automasking_topology = True
brush.mesh_automasking_settings.cavity_factor = 0.5

All 17 properties: use_automasking_topology, use_automasking_face_sets, use_automasking_boundary_edges, use_automasking_boundary_face_sets, use_automasking_cavity, use_automasking_cavity_inverted, use_automasking_start_normal, use_automasking_view_normal, automasking_boundary_edges_propagation_steps, automasking_cavity_factor, automasking_cavity_blur_steps, automasking_cavity_curve, automasking_cavity_curve_op, automasking_start_normal_limit, automasking_start_normal_falloff, automasking_view_normal_limit, automasking_view_normal_falloff

5. VSE strip.use_linear_modifiers Removed

6. VSE timecode files Feature Removed

7. UILayout.template_palette color Parameter Removed

8. Compare / Random Value Node Socket Identifiers Changed

9. Asset Library Index Shift — "All Libraries" and "Essentials" now occupy first two indices

10. Evaluated Meshes Naming Change — Geo Nodes created meshes no longer share object's original mesh name

11. Brush use_* → stroke_method (see 5.1 section above)

12. VSE Time Property Renames (see 5.1 section above)

---

🟢 High-Value New APIs (5.2 LTS)#

Python API

APIDescriptionbpy.data.all_idsSingle iterator over ALL data-blocksWindowManager.reportsRead-only reports list with session-wide unique uidbpy.data.libraries.load() inputNow exposes nested library pathsWindow.screenshot()Get window pixel data without saving to filegpu.init()Initialize GPU backend in --background modemathutils slice stepvector[begin:end:step] for Vector/Matrix/Color/EulerBlender Arrays slice stepimage.pixels[begin:end:step] — e.g., pixels[3::4] for alpha channelpath_foreach optionsEXPAND_TOKENS, EXPAND_SEQUENCES, EXPAND_CACHESAnnotations APIframe.strokes.new(), stroke.points.add(count, pressure, strength), stroke.points.remove(index), frame.strokes.remove(stroke)``UILayout.link / textboxStyled link buttons and multi-line text buttonsimbuf extendedPixel-level image access, format conversion, buffer protocolNode panel collapseProgrammatically open/close node panels from PythonNode Tool input valuesSet Node Tool parameters programmatically in 5.2

Geometry Nodes

Node / FeatureDescriptionPhysics (experimental)XPBD Solver, Cloth Dynamics modifier, Hair Dynamics, Effector systemMesh BevelLong-awaited procedural bevel nodeGeometry BundlesSet/Get Geometry Bundle — attach arbitrary data (fields, closures) to geometryLists data typeNew core type alongside single/field/grid — Length, Get, Filter, SortSample Sound FrequenciesAudio-driven animation without keyframe bakingPCAPrincipal Component Analysis for auto-alignmentTransfer AttributesTransfer attributes between two geometries3D ↔ Screen SpaceBundled transform nodes (3D to Screen, Screen to 3D, Project with Depth)Collection ChildrenRecursive access to collection children as listsEmpty ObjectsGeo Nodes modifiers on Empty objectsCapture Attribute SelectionSelection input for efficiencyNURBS Order/WeightSet NURBS Order and Weight nodesScene Frame default inputFloat/int sockets default to current frameSelf-object defaultObject sockets can default to self-objectMerge by Distance splitNow: Merge Points + Cluster by Distance + Cluster by Connected

Cycles

FeatureDescriptionTexture Cache.tx files reduce memory 34-77% in texture-heavy scenes. Enable: Performance > Texture Cache + Auto Generate. CLI: blender scene.blend --command maketxRaycast AttributesAccess attributes at intersection point (Cycles only)SSS Negative AnisotropyPrincipled/Subsurface BSDF: -1 to 1 rangeWorld Cast ShadowsWorld can now cast shadowsOSL GPUTexture cache improves OSL performance + adds GPU supportSimplify Texture ResolutionPercentage-based texture scaling (50%, 25%)

EEVEE

FeatureDescriptionShader RaycastScreen-space raytracing nodeLight Path IntensityGlobal indirect light intensity control**Texture pool -40%**Vulkan: 406MB → 245MB

Grease Pencil

FeatureDescriptionFill Tool DelaunayNew Delaunay solver: precise geometry, auto gap detection, scale-independent, fasterDraw Tool curvesBézier / Catmull-Rom / NURBS curve typesLine Materials placementCount / Density / Radius modes with randomization**layer.layer_masks API**Add/remove layer masks via Python

Video Sequencer

FeatureDescriptionCompositor Effect StripUse compositor node trees for VSE transitions/effects (0/1/2 inputs + fader)Compositor GPU accelerationIn VSE modifiers**strip.connections**API to find connected strips

Sculpt

FeatureDescriptionScene Project brushDisplace vertices toward other objects (like Shrinkwrap)Add Primitive in Sculpt ModeCube/Cone/Cylinder directly in sculptColor Filter unified colorUses scene unified colors; Ctrl-X quick fillDyntopo confirmation removedNo more confirmation dialog when switching back to SculptVoxel Remesher attribute interpolationSmooth vertex/corner attribute interpolation

Assets

FeatureDescriptionOnline Asset LibraryBrowse and download from remote hosted librariesAsset Library index shift"All Libraries" and "Essentials" now at indices 0 and 1

Other

FeatureDescriptionLoopTools built-inCircle/Space/Flatten now native — no addon neededHydra 2.0 APIOpenUSD provides abstraction layer**Animation +125%**Action evaluation 32.8→74.1 fps (4 threads)Gaussian Smooth F-CurveNon-destructive curve smoothing modifier

---

Blender 5.3 Compatibility Notes (Beta — API 已稳定)#

5.3 = Beta（分支 blender-v5.3-release）。官方 release notes 首页原文： "Blender 5.3 is currently in Beta until November 4, 2026"（= RC 节点）→ 正式发布 2026-11-10。 官方 release cycle 明确「 Beta 期间 Python API 保持稳定，add-ons 有时间在发布前完成适配」→ 5.3 兼容代码现在就可以定版。 生产基准仍是 5.2.x LTS（当前 5.2.2）；5.4 处于 Alpha， 不承诺、不跟。 📝 最后核验： 2026-10-11（ /api/5.3/ 章节 131 条 + 5.3 release notes 首页/python_api 全页；完整条目与迁移清单见 knowledge/blender/api-changes-5.3.md）

🔴 5.3 Breaking Changes（8 组，详见知识库）#

📝 最后扫描：2026-09-07 11:00 — 完整官方 change_log 核实

GPU 兼容性变更 (09-06)

python

# ⚠️ gpu.types.GPUBatch.draw_instanced 行为变更
# 现在优先使用 gpu_InstanceIndex（包含 base_instance）
# 与 Metal/Vulkan 内部工作方式对齐
# commit: 6f64632716
# 影响：使用自定义 GPU 着色器的插件需要测试兼容性

🔴 NodesModifier.panels 移除 (09-07 新发现！关键！)

python

# ❌ 5.2 及更早
modifier.panels  # 访问 Geo Nodes 修饰器的面板属性

# ✅ 5.3+ — 已移除！
# Geo Nodes 修饰器不再有 panels 属性
# 兼容写法：
import bpy
if bpy.app.version >= (5, 3, 0):
    # 使用 modifier.properties.inputs/outputs 替代
    pass
else:
    panels = modifier.panels

🔴 Theme API 移除 (09-07 新发现)

python

# ❌ 以下主题属性在 5.3 中已移除：
# ThemeFileBrowser.selected_file
# ThemeSpaceGeneric.header_text / header_text_hi / title
# ThemeSpaceGradient.header_text / header_text_hi / title

# 影响：自定义主题插件需要移除对这些属性的引用

Brush Unified Input 属性重命名 (4 项，09-07 修正映射)

python

# ❌ 5.2 及更早
brush.use_inverse_smooth_pressure = True

# ✅ 5.3+（09-07 官方确认的新名称）
brush.use_smooth_pressure = True        # ← use_inverse_smooth_pressure 重命名而来
brush.use_unified_input_samples = True  # ← 新增统一输入属性
brush.use_unified_strength = True       # ← 新增统一强度属性
brush.use_unified_weight = True         # ← 新增统一权重属性

# 兼容写法：
import bpy
if bpy.app.version >= (5, 3, 0):
    brush.use_smooth_pressure = True
else:
    brush.use_inverse_smooth_pressure = True

PreferencesExperimental 重命名 (1 项)

python

# ❌ 5.2
prefs.experimental.use_sculpt_texture_paint

# ✅ 5.3+
prefs.experimental.use_3d_texture_paint

PreferencesSystem 重命名 (1 项)

python

# ❌ 5.2
prefs.system.geometry_nodes_stack_limit

# ✅ 5.3+
prefs.system.nodes_stack_limit

🔴 SpaceOutliner 过滤器重命名 (10 项，09-23 补充来源信息！关键！)

python

# ❌ 5.2 及更早
outliner.use_sort_alpha = True  # 单个属性控制字母排序

# ✅ 5.3+ — 拆分为 10 个独立过滤器属性！
# 每个对象类型/数据类型都有独立的过滤器控制
outliner.use_filter_object_materials = True
outliner.use_filter_object_modifiers = True
outliner.use_filter_object_constraints = True
outliner.use_filter_object_shape_keys = True
outliner.use_filter_object_vertex_groups = True
outliner.use_filter_object_data = True
outliner.use_filter_object_animation = True
outliner.use_filter_bone_collections = True
outliner.use_filter_pose_bones = True
outliner.use_filter_grease_pencil_effects = True

# 兼容写法：
import bpy
if bpy.app.version >= (5, 3, 0):
    # 使用新的独立过滤器
    outliner.use_filter_object_materials = True
else:
    # 旧版本使用 use_sort_alpha
    outliner.use_sort_alpha = True

🔴 UserAssetLibrary 属性重命名 (3 项，09-23 补充来源信息！)

python

# ❌ 5.2 及更早
library.path = "/path/to/asset"

# ✅ 5.3+ — 拆分为 3 个独立属性
library.auth_token = "token"  # 认证令牌
library.invalid_uuid = "uuid"  # 无效 UUID
library.uuid = "uuid"  # 资产库 UUID

# 兼容写法：
import bpy
if bpy.app.version >= (5, 3, 0):
    # 使用新的独立属性
    library.auth_token = token
    library.uuid = uuid
else:
    # 旧版本使用 path
    library.path = path

🔴 函数签名变更（2026-10-05 新增发现！易静默出错）

python

# ❌ 旧签名（≤5.2）
bpy.types.ObjectConstraints.new(type)                 # 只传 type
bpy.types.PoseBoneConstraints.new(type)
layout.textbox(data, property, initial_visible_lines, placeholder, text_ctxt, translate)

# ✅ 5.3+
bpy.types.ObjectConstraints.new(type, name)           # 多了一个 name
bpy.types.PoseBoneConstraints.new(type, name)
layout.textbox(data, property, text, text_ctxt, translate,
               initial_visible_lines, placeholder)    # ⚠️ 位置参数被重排！

# 安全做法：全部改用关键字传参
layout.textbox(data, property, text=text, text_ctxt="", translate=False,
               initial_visible_lines=3, placeholder="")

# WindowManager.popover / popover_begin__internal：新增 auto_keymap 参数
bpy.context.window_manager.popover(draw_func, ui_units_x=8, keymap="", from_active_button=False, auto_keymap=True)

影响：任何按位置传参调用 textbox / textbox_with_state / Constraints.new 的插件，在 5.3 上会 静默传错值 或抛 TypeError。

🟢 2026-10-05 其他新增（精选）

API说明插件价值BlendFileColorspace.is_failed_opencolorio_config / ocio_config_path / ocio_config_sourceOCIO 配置诊断色彩管线插件能定位色彩管理失败原因MaterialGPencilStyle.gradientGP 材质渐变Grease Pencil 材质插件SpaceOutliner.show_users_column / sort_method大纲用户列 / 排序方式大纲 UI 插件UILayout.label_markdownUI 渲染 Markdown 文本帮助/文档类面板

🟡 5.3 High-Value New APIs (精选)#

Python API 新增 (09-11 完整扫描 - 4 项新增，累计 50+ 项)

🔥 最新新增（09-11）:

API说明插件开发价值RenderEngine.bl_write_viewport_depth自定义渲染引擎写入视口深度缓冲自定义渲染器插件FileHandler.label_with_extensions文件处理器显示带扩展名的标签导入/导出插件UILayout.label_markdownUI 布局中渲染 Markdown 格式文本UI 插件增强CyclesPreferences.has_dlss_gpu_devicesDLSS GPU 设备检测渲染设置插件CyclesRenderSettings.preview_denoising_upscale_quality预览降噪升级质量渲染控制插件RegionView3D.use_view_flip_x视口水平翻转视口控制插件SpaceNodeOverlay.show_text_info节点叠加层文本信息节点编辑器插件

📋 之前扫描的高价值新增（插件开发必备）:

API说明插件开发价值Project APIBlendData.project / project_init() / project_clear()项目管理插件Preferences.use_project_auto_save项目自动保存设置项目管理集成Render Pause/ResumeRenderEngine.view_pause() / view_resume()渲染控制插件RegionView3D.pause_render / support_pause_render视口渲染暂停视口控制插件CYCLES.view_pause / view_resumeCycles 渲染暂停渲染控制插件Scene Compositor EffectsScene.compositor_effects场景级合成效果CompositorNodeTree.allow_usage_in_scene_compositor_effect允许节点树用于场景合成合成插件ID deep_hashID.deep_hash 基于内容的哈希数据块去重/缓存Outliner 11 细粒度过滤器use_filter_object_materials/modifiers/constraints/shape_keys/vertex_groups/data/animation + use_filter_bone_collections/pose_bones/grease_pencil_effects大纲视图插件**⚠️ Outliner 过滤器重命名**use_sort_alpha → 10 个 use_filter_* 属性（破坏性变更！）大纲插件迁移UILayout.template_compositor_strip_inputs合成器 Strip 输入模板VSE 插件UILayout.template_scene_compositor_effects场景合成效果模板合成 UI 插件RegionView3D.view_camera_roll相机旋转控制相机控制插件Window.global_areas全局区域访问窗口管理插件

📦 Asset Library 增强 (09-07 新发现):

API说明插件开发价值UserAssetLibrary.auth_token资产库认证令牌在线资产库插件UserAssetLibrary.use_auth_token启用认证在线资产库插件UserAssetLibrary.uuid / invalid_uuid资产库 UUID资产库管理UserAssetLibrary.is_project_defined项目定义的资产库项目资产管理AssetMetaData.webpage资产网页链接资产浏览器插件

🎨 Brush 增强 (09-07 新发现):

API说明插件开发价值Brush.curve_auto_smooth自动平滑曲线笔刷插件Brush.curve_hardness硬度曲线笔刷插件Brush.curve_spacing间距曲线笔刷插件Brush.use_unified_color统一颜色笔刷插件Brush.use_unified_size统一尺寸笔刷插件BrushCapabilitiesSculpt.has_tip_roundness笔尖圆润度能力雕刻插件

🔧 其他新增 (09-07 扫描):

API说明插件开发价值Object.convert_rotation_mode()旋转模式转换动画插件PoseBone.convert_rotation_mode()骨骼旋转模式转换动画插件ViewLayerEEVEE.denoising_store_passes降噪存储通道EEVEE 渲染插件ViewLayerEEVEE.denoising_pass_use_albedo_roughness_weighting降噪权重EEVEE 渲染插件PreferencesEdit.clamp_strips_by_defaultVSE Strip 默认限制VSE 插件PreferencesEdit.default_strip_lengthVSE 默认 Strip 长度VSE 插件PreferencesSystem.use_rt_shadows光线追踪阴影渲染设置插件Region.search_filter区域搜索过滤UI 插件ToolSettings.use_transform_data_pivot变换数据枢轴变换工具插件Collection.importer集合导入器导入插件CollectionImport.filepath导入文件路径导入插件Scene.wrap_timeline_navigation时间线循环导航动画插件SpaceDopeSheetEditor.cache_compositor合成缓存动画/合成插件RenderSettings.use_compositor_frames_cache合成帧缓存渲染插件SceneEEVEE.time_limitEEVEE 时间限制EEVEE 渲染插件SpaceOutliner.expand_on_focus大纲展开行为大纲 UI 插件SpaceProperties.show_properties_compositor显示合成属性属性 UI 插件BrushGpencilSettings.use_cyclic_strokeGrease Pencil 循环笔触GP 笔刷插件PointCloud.type点云类型属性点云数据处理插件

🆕 最新新增 (09-23 扫描 - 8 项):

API说明插件开发价值CollectionChild.sort_index集合子对象排序索引集合管理插件CollectionObject.sort_index集合对象排序索引集合管理插件CollectionObject.parented_sort_index集合对象父级排序索引集合管理插件ColorManagedInputColorspaceSettings.interop_id输入色彩空间互操作ID色彩管理插件ColorManagedSequencerColorspaceSettings.interop_id序列编辑器色彩空间互操作ID色彩管理/序列编辑器插件CompositorNodeConvertColorSpace.from_interop_id色彩空间转换节点源互操作ID合成节点插件CompositorNodeConvertColorSpace.to_interop_id色彩空间转换节点目标互操作ID合成节点插件SpaceOutliner.sort_method大纲排序方法大纲 UI 插件

Geometry Nodes 新增 (09-06 扫描)

节点/功能说明插件开发价值Combine List合并多个列表列表数据处理增强Get Vector Component通过整数索引获取 x/y/z 分量向量操作简化Rasterize Points将点转换为栅格（光栅化）点云→网格转换Deactivate Voxels从体积栅格中移除活动体素体积数据处理Grid Topology Boolean活动栅格体素的布尔运算体积建模NURBS input nodesNURBS 输入节点组NURBS 曲线控制Curve to Mesh "Miter Scale"斜接缩放选项曲线转网格控制Curve to Tube "Miter Scale"斜接缩放选项管道建模Realize Instances "Preserve Normals"保留负变换行列式实例的法线实例化处理GP data input nodesGrease Pencil 数据输入节点GP 数据处理Grid sampling modes改进的二次/三次采样模式栅格采样质量

完整变更记录#

详见工作区知识库 knowledge/blender/api-changes-5.2-lts.md 与 knowledge/blender-mcp/research-tracker.md

---

OpenClaw Integration#

Configure openclaw.json#

json

{
  "plugins": {
    "entries": {
      "mcp": {
        "servers": {
          "blender-mcp": {
            "command": "python",
            "args": ["-m", "blmcp", "--transport", "stdio"],
            "cwd": "path/to/blender_mcp",
            "env": {
              "BLENDER_MCP_HOST": "localhost",
              "BLENDER_MCP_PORT": "9876"
            }
          }
        }
      }
    }
  }
}

Via mcporter CLI#

bash

# List tools
mcporter call blender-mcp.get_objects_summary

# Execute code
mcporter call blender-mcp.execute_blender_code code='import bpy; result = {"count": len(bpy.data.objects)}'

---

Geometry Nodes MCP Integration#

The official Blender MCP Server supports advanced Geometry Nodes inspection and debugging capabilities (Blender 5.2+):

Querying Data Relations#

bash

# Find which objects use a specific material
mcporter call blender-mcp.execute_blender_code code='
import bpy
material_name = "pebbles"
users = [obj.name for obj in bpy.data.objects if obj.active_material and obj.active_material.name == material_name]
result = {"material": material_name, "users": users, "count": len(users)}
'

Scene Debugging#

bash

# Find highest poly-count object in scene
mcporter call blender-mcp.execute_blender_code code='
import bpy
mesh_objects = [(obj.name, len(obj.data.polygons)) for obj in bpy.data.objects if obj.type == "MESH"]
if mesh_objects:
    highest = max(mesh_objects, key=lambda x: x[1])
    result = {"object": highest[0], "faces": highest[1]}
else:
    result = {"error": "No mesh objects found"}
'

Geometry Node Tree Inspection#

bash

# Inspect Geometry Nodes modifier connections
mcporter call blender-mcp.execute_blender_code code='
import bpy
obj = bpy.data.objects["GEO-pebble"]
if obj.modifiers:
    mod = obj.modifiers[0]
    if mod.type == "NODES":
        node_tree = mod.node_group
        nodes_info = [{"name": n.name, "type": n.type, "inputs": [i.name for i in n.inputs]} for n in node_tree.nodes]
        result = {"modifier": mod.name, "node_tree": node_tree.name, "nodes": nodes_info}
    else:
        result = {"error": "Not a Geometry Nodes modifier"}
else:
    result = {"error": "No modifiers found"}
'

Common Geometry Nodes MCP Patterns#

TaskExample QueryFind material users"Which objects use the material: [name]"Scene density analysis"Analyze mesh density distribution in this scene"Debug missing data"What is the object with the highest poly-count?"Node tree structure"Show me the Geometry Nodes connections for [object]"

---

Gemini CLI Integration#

Blender MCP can be used with Google Gemini CLI (in addition to Claude):

bash

# Install Gemini CLI
npm install -g @google/gemini-cli

# Configure MCP via Gemini CLI's built-in command
gemini mcp add blender --transport stdio --command "uvx blender-mcp@1.0.0" --env BLENDER_MCP_HOST=localhost --env BLENDER_MCP_PORT=9876

# Start Gemini CLI with Blender MCP
gemini

Security Note / 安全说明: The gemini mcp add command automatically creates the configuration in the appropriate location. No manual file editing is required.

---

Quick Start Checklist#

• Blender 5.1+ installed
• MCP Addon installed and enabled
• Auto Start enabled (optional, recommended)
• MCP Server started ( python -m blmcp --transport stdio or uvx blender-mcp@1.0.0)
• mcporter installed ( npm install -g mcporter)
• Port 9876 available (default)
• BLENDER_PATH environment variable set (if needed)
• DISABLE_TELEMETRY=true (optional, for privacy)

---

Changelog#

v3.3.0 (2026-10-13) — 官方 issue/PR 实证取证 + 工具行为排障补强（每日快扫）#

• 🟢 取证渠道修复： projects.blender.org 的 HTML 页面长期 403，改走 Gitea REST API（ /api/v1/repos/lab/blender_mcp/{releases,issues,pulls}）→ issue/PR 状态首次拿到官方实证（此前 10 天只能写"未能核查"）
• 🟢 add-on 版本核实：最新发布仍是 v1.0.3（2026-09-11），无 v1.0.4（官方 releases API + 落地页双向印证）；Open PR = #48 / #47 / #43（均未合并）
• 🟢 排障表新增 7 条官方 issue 可溯源的工具行为坑： *_for_cli Windows stdio 挂死（#58/#60，PR #48）｜ execute_blender_code 每次新命名空间（#55）｜ get_objects_summary 上下文爆炸（#54）｜缩略图分辨率与临时目录语义（#46/#61/#53）｜ get_python_api_docs 需重复类名（#62）｜macOS .mcpb 安装失败（#57）｜Windows SAC 拦截（#56）
• ⚠️ 更正：作废追踪表中不存在的 #344 / #345 / #348（官方 API 实测 404）；新增"不得用搜索摘要代替官方源"的取证规则
• 📌 API 侧同步：change_log 本轮 8 条新条目中 7 条实际 5.3 生效（项目系统 + UILayout 模板，见 api-changes-5.3.md §7）、1 条 5.4 独有（ Mesh.use_radial_symmetry，见 §3.6）—— 均不触及 MCP 执行路径，MCP 侧无兼容性改动
• ✅ 三处版本号一致： SKILL.md frontmatter / README 版本行 / 两处 Changelog = 3.3.0； 双平台发布仍待用户确认（v3.2.0 未发布 → 本次发布一并覆盖两版变更）

v3.2.0 (2026-10-11) — 5.3 Beta 口径 + 官方安装链接 + 排障补强（周度整合）#

• 🟢 5.3 兼容章节标题由「dev — 前瞻」改为「 Beta — API 已稳定」，并写明 RC 2026-11-04 → 发布 2026-11-10（官方 release notes 首页原文）
• 🟢 安装步骤改用官方 add-on v1.0.3 链接（原写 v1.0.0 已过期），补 Blender ≥ 5.1 硬性要求与「拖拽要拖两次」说明
• 🟢 排障表新增 4 条高频真实坑： Auto Start 只在启动时触发 / 两个 MCP add-on 抢 9876 端口 / Allow Online Access / 拖拽安装要拖两次
• 📌 同步两条 5.3 生效的 API 变更口径（ use_collection_importer 移除、资产库进度回调 3 参数）—— 官方已于 2026-10-11 把它们补登进 /api/5.3/ 章节
• ✅ 版本号三处一致： SKILL.md frontmatter / README 版本行 / 两处 Changelog 均为 3.2.0； 双平台发布待用户确认

v3.1.1 (2026-10-08) — 文档一致性修复#

• ✅ README 变更日志补齐 v3.0.0 / v3.1.0 / v3.1.1（修复「版本行 3.1.0、正文停在 v2.5.9」的版本漂移）
• ✅ 核验日期更新至 2026-10-07（每日快扫 10-06 / 10-07 均无 API 增量）
• ✅ 无 API 内容变更，纯文档版本

v3.1.0 (2026-10-05) — 5.3 全量核验#

• 🔴 新增破坏性变更：函数签名变更（ ObjectConstraints.new/ PoseBoneConstraints.new 增加 name； UILayout.textbox/ textbox_with_state 位置参数重排； WindowManager.popover* 新增 auto_keymap）
• 🟢 新增发现： BlendFileColorspace OCIO 诊断三项、 MaterialGPencilStyle.gradient、 SpaceOutliner.show_users_column/ sort_method、 UILayout.label_markdown
• 📌 完整条目迁移到 knowledge/blender/api-changes-5.3.md；本文件保留速览与兼容模板

v3.0.0 (2026-10-05) — Workspace Rebuild#

• 迁移到 octop 工作区：知识库拆到 knowledge/blender-mcp/（research-tracker、auto-publish-workflow）
• 移除 openclaw 专用安装元数据，改为 octop 技能元数据
• 研究追踪与发布流程改由 blender-autolearn 技能 + 定时任务驱动

v2.5.9 (2026-09-23) — Security Release#

• 🔒 Removed dangerous curl | sh pattern from installation docs
• 🔒 Added bilingual security warnings (EN/CN) about bpy code execution risks
• 🔒 Pinned dependency versions: uvx blender-mcp==1.0.0, pip install mcp==1.8.0 pyyaml==6.0.2 starlette==0.45.0
• 🔒 Clarified telemetry defaults and opt-out mechanism
• 🔒 Added bilingual documentation throughout (EN/CN)
• 🔒 Removed publish scripts from skill directory (unrelated to skill functionality)

v2.5.8 (2026-09-23)#

• ✅ 5.3 Alpha API 增量更新 (09-23): 基于官方 change_log 第七次扫描
• ✅ 新增 CollectionChild.sort_index: 集合子对象排序索引
• ✅ 新增 CollectionObject.sort_index: 集合对象排序索引
• ✅ 新增 CollectionObject.parented_sort_index: 集合对象父级排序索引
• ✅ 新增 ColorManagedInputColorspaceSettings.interop_id: 输入色彩空间互操作ID
• ✅ 新增 ColorManagedSequencerColorspaceSettings.interop_id: 序列编辑器色彩空间互操作ID
• ✅ 新增 CompositorNodeConvertColorSpace.from_interop_id: 色彩空间转换节点源互操作ID
• ✅ 新增 CompositorNodeConvertColorSpace.to_interop_id: 色彩空间转换节点目标互操作ID
• ✅ 新增 SpaceOutliner.sort_method: 大纲排序方法
• ✅ 补充破坏性变更: SpaceOutliner 的 use_sort_alpha 重命名为 10 个 use_filter_* 属性
• ✅ 补充破坏性变更: UserAssetLibrary 的 path 重命名为 auth_token/invalid_uuid/uuid
• ✅ 总计: 8 项新增 API + 2 项重要重命名文档补充 (集合排序/色彩空间互操作/大纲排序)

v2.5.7 (2026-09-20)#

• ✅ 5.3 Alpha API 增量更新 (09-20): 基于官方 change_log 第六次扫描
• ✅ 新增 BrushGpencilSettings.use_cyclic_stroke: Grease Pencil 循环笔触设置
• ✅ 总计: 1 项新增 API (GP 笔刷增强，无破坏性变更)

v2.5.6 (2026-09-18)#

• ✅ 5.3 Alpha API 增量更新 (09-18): 基于官方 change_log 第五次扫描
• ✅ 新增 PointCloud.type: 点云类型属性
• ✅ 总计: 1 项新增 API (点云数据增强，无破坏性变更)

v2.5.5 (2026-09-16)#

• ✅ 5.3 Alpha API 增量更新 (09-16): 基于官方 change_log 第四次扫描
• ✅ 新增 RenderEngine.bl_write_viewport_depth: 自定义渲染引擎写入视口深度缓冲
• ✅ 新增 FileHandler.label_with_extensions: 文件处理器显示带扩展名的标签
• ✅ 新增 UILayout.label_markdown: UI 布局中渲染 Markdown 格式文本
• ✅ 总计: 3 项新增 API (均为渲染/文件处理/UI 增强，无破坏性变更)

v2.5.4 (2026-09-11)#

• ✅ 5.3 Alpha API 增量更新 (09-11): 基于官方 change_log 三次扫描
• ✅ 新增 CyclesPreferences.has_dlss_gpu_devices: DLSS GPU 设备检测
• ✅ 新增 CyclesRenderSettings.preview_denoising_upscale_quality: 预览降噪升级质量
• ✅ 新增 RegionView3D.use_view_flip_x: 视口水平翻转
• ✅ 新增 SpaceNodeOverlay.show_text_info: 节点叠加层文本信息显示
• ✅ 总计: 4 项新增 API (均为渲染/视口/节点 UI 增强，无破坏性变更)

v2.5.3 (2026-09-10)#

• ✅ 5.3 Alpha API 增量更新 (09-10): 基于官方 change_log 二次扫描
• ✅ 新增 WindowManager.undo_stack: 编程访问撤销栈
• ✅ 新增 UILayout.property_split_factor: 属性分割系数控制
• ✅ WindowManager.invoke_popup 参数变更: 新增 auto_keymap 参数
• ✅ WindowManager.popover 参数变更: 新增 auto_keymap 参数
• ✅ WindowManager.popover_begin__internal 参数变更: 新增 auto_keymap 参数
• ✅ 总计: 5 项新增/变更 API (均为 UI/窗口管理增强，无破坏性变更)

v2.5.2 (2026-09-10)#

• ✅ 版本号同步至 2.5.2（与 GitHub/ClawHub 对齐）

v2.5.1 (2026-09-09)#

• ✅ 5.3 Alpha API 增量更新 (09-09): 基于官方 change_log 扫描
• ✅ 新增 Cycles 元数据属性: BatchRenameAction.name, CyclesCurveRenderSettings.name, CyclesCustomCameraSettings.name, CyclesLightSettings.name, CyclesMaterialSettings.name, CyclesMeshSettings.name, CyclesObjectSettings.name, CyclesRenderLayerSettings.name, CyclesRenderSettings.name, CyclesView3DShadingSettings.name, CyclesVisibilitySettings.name, CyclesWorldSettings.name
• ✅ 新增 GLTF2_filter_action.name
• ✅ 新增 NodeSetting.name
• ✅ 新增 Paint 可视化曲线: Paint.show_auto_smooth_curve, Paint.show_hardness_curve, Paint.show_spacing_curve
• ✅ 新增 CompositorStrip.properties
• ✅ 新增 SequencerTimelineOverlay.show_thumbnails
• ✅ 总计: 18 项新增 API (均为小功能增强，无破坏性变更)

v2.5.0 (2026-09-08)#

• ✅ 跟踪 blender-mcp 社区 PR（3 项重要改进，均为 OPEN 状态）：

  • 🔴 PR #348: Server instructions 机制 - 通过 FastMCP(instructions=...) 传递代码正确性指南

    • 解决 #26（本地化 UI 中 nodes["Principled BSDF"] 返回 None）
    • 解决 #110（渲染引擎标识符在版本间不一致）
    • 使用 n.type == "BSDF_PRINCIPLED" 而非节点名称（跨语言兼容）
    • 使用 try/except TypeError 获取动态枚举的完整值列表

  • 🟡 PR #344: export_scene 命令 - 场景导出为第一类工具

    • 支持 GLB/FBX 格式导出到自定义路径
    • 参数： filepath, format="glb", object_names=None, selection_only=False, apply_modifiers=True
    • 自动处理选择、修改器烘焙、GLB 标志位
    • 返回： {path, bytes, selection_only, exported: [...]}

  • 🟡 PR #345: 插件自动启动改进 - 延迟启动 + 重试机制

    • 使用 Blender 持久化定时器延迟启动（避免冷启动时序问题）
    • 等待场景存在后使用配置的端口
    • 启动失败后自动重试
    • 文件加载后重新调度
    • 手动断开不会被后续文件加载覆盖
• ✅ Blender API 无新变更（change_log 与 2026-09-07 一致）

v2.4.0 (2026-09-07)#

• ✅ 5.3 Alpha 完整扫描 (09-07): 基于官方 change_log.html 全量核实
• 🔴 新增破坏性变更: NodesModifier.panels 移除（Geo Nodes 插件关键影响！）
• 🔴 Theme API 移除: ThemeFileBrowser.selected_file, ThemeSpaceGeneric/Gradient.header_text/header_text_hi/title
• ✅ Brush 重命名修正: use_inverse_smooth_pressure → use_smooth_pressure（非反向）
• ✅ 新增 Project API: BlendData.project/project_init/project_clear + Preferences.use_project_auto_save
• ✅ 新增渲染暂停/恢复: RenderEngine.view_pause/view_resume, RegionView3D.pause_render
• ✅ 新增场景合成效果: Scene.compositor_effects, CompositorNodeTree.allow_usage_in_scene_compositor_effect
• ✅ 新增 ID.deep_hash: 数据块内容哈希
• ✅ 新增 Outliner 11 项细粒度过滤器
• ✅ 新增 UILayout 合成模板: template_compositor_strip_inputs, template_scene_compositor_effects
• ✅ 新增 Asset Library 认证: UserAssetLibrary.auth_token/use_auth_token/uuid
• ✅ 新增 Brush 曲线/统一属性: curve_auto_smooth/curve_hardness/curve_spacing/use_unified_color/use_unified_size
• ✅ 新增旋转模式转换: Object/PoseBone.convert_rotation_mode()
• ✅ 新增 EEVEE 降噪: ViewLayerEEVEE.denoising_store_passes
• ✅ 新增 VSE 偏好设置: PreferencesEdit.clamp_strips_by_default/default_strip_length
• ✅ 新增 RT Shadows: PreferencesSystem.use_rt_shadows
• ✅ 新增 Collection Import: Collection.importer, CollectionImport.filepath
• ✅ 总计: Python API 50+ 项新增 + 6 项移除 + 5 项重命名

v2.3.0 (2026-09-06)#

• ✅ 5.3 Alpha 扫描更新 (09-06): Python API 6 项新增 + Geo Nodes 13 项新增 + GPU 兼容性变更
• ✅ 新增 NodeTreeInterface.root_panel, UILayout.label_multiline(), WindowManager.try_activate_rna_button()
• ✅ 新增 mathutils.KDTree 2D 树支持 + bpy.data.all_ids 顺序变更警告
• ✅ 新增 Geo Nodes: Combine List, Get Vector Component, Rasterize Points, Deactivate Voxels, Grid Topology Boolean, NURBS input nodes, Curve to Mesh/Tube Miter Scale, Realize Instances Preserve Normals, GP data input nodes
• ✅ 新增 GPU 兼容性变更: gpu.types.GPUBatch.draw_instanced 行为变更 (commit 6f64632716)

v2.2.0 (2026-09-04)#

• ✅ Added Geometry Nodes MCP integration section with debugging examples
• ✅ Documented Auto Start feature for addon preferences
• ✅ Added uvx quick installation method
• ✅ Added DISABLE_TELEMETRY environment variable
• ✅ Added Gemini CLI integration guide
• ✅ Enhanced Quick Start Checklist with new options

v2.1.0 (Previous)#

• Blender 5.2 LTS Beta API compatibility notes
• 12 breaking changes documented
• 66 new APIs catalogued