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-16（每日快扫：add-on 仍 v1.0.3（最新发布 2026-09-11，无 v1.0.4），落地页可比基线连续 8 次一致；MCP 仓库 open issues 18 → 21，新增 #63（Windows SO_REUSEADDR 让第二个 Blender 静默绑定已占用端口 → 客户端始终连第一个实例）与 #64（result 必须为 dict，官方 server instructions 说可返回 list 属文案误导）→ 排障表补 2 条；完整清单见 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

┌─────────────┐     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 / 最简单)

# 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

# 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

# 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)

# 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.

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)

# 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

Scene Analysis

Screenshots & Rendering

Navigation

Documentation Search

Communication Protocol

TCP Socket Protocol

Request format (null-byte delimited JSON):

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

Response format:

// 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

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

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

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

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

# 仓库 / 发布 / 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:

# ❌ 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

# ❌ 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

Principled BSDF Input Renames

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

# ❌ 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)

# ❌ 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

Geometry Nodes

Cycles

EEVEE

Grease Pencil

Video Sequencer

Sculpt

Assets

Other

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)

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

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

# ❌ 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 新发现)

# ❌ 以下主题属性在 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 修正映射)

# ❌ 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 项)

# ❌ 5.2
prefs.experimental.use_sculpt_texture_paint

# ✅ 5.3+
prefs.experimental.use_3d_texture_paint

PreferencesSystem 重命名 (1 项)

# ❌ 5.2
prefs.system.geometry_nodes_stack_limit

# ✅ 5.3+
prefs.system.nodes_stack_limit

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

# ❌ 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 补充来源信息！)

# ❌ 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 新增发现！易静默出错）

# ❌ 旧签名（≤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 其他新增（精选）

🟡 5.3 High-Value New APIs (精选)

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

🔥 最新新增（09-11）:

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

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

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

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

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

Geometry Nodes 新增 (09-06 扫描)

完整变更记录

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

OpenClaw Integration

Configure openclaw.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

# 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

# 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

# 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

# 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

Gemini CLI Integration

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

# 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.4.0 (2026-10-16) — 2 条新官方 issue 工具行为坑（每日快扫）

• 🟢 排障表新增 2 条官方 issue 可溯源的工具行为坑：
  • issue #63：Windows 上 SO_REUSEADDR 让第二个 Blender 实例静默绑定已占用端口 → 服务按钮显示"已启动"但客户端始终连第一个实例（表现：操作落到别的窗口 / 改了没反应）。创建者实测 20/20 复现（Win11 + Blender 5.2.2 LTS + blender_mcp 1.0.2），建议官方改用 SO_EXCLUSIVEADDRUSE → 技能给处置：只开一个实例 / 先关旧实例 / netstat -ano | findstr 9876 查占用
  • issue #64：execute_blender_code 的 result 必须为 dict；官方 prompts.yml L48 声称可返回 "dicts, lists" 属文案与实现不一致（报错原文 The result variable must be a dict, not list. Wrap your return value: result = {"key": value}）→ 技能给处置：一律包成 dict
• 📌 MCP 仓库快照：最新发布仍 v1.0.3（2026-09-11，无 v1.0.4）；落地页 add-on 链接可比基线连续 8 次一致；Open issues 18 → 21；Open PR #48 / #47 / #43 仍全部未合并
• ✅ 版本号三处一致：SKILL.md frontmatter / README 版本行 / 两处 Changelog = 3.4.0；双平台发布待用户确认（远端已发布基线仍是 v3.3.0）

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