Blender MCP（本地）

把 DSH 接到本机正在运行的 Blender：一个本地 MCP 服务器 + 一个 Blender addon。默认暴露 12 个基础工具，由 AI 自主编写建模和材质脚本；兼容模式提供全部 52 个工具。

这是 ptc-model-check 的配套包，两个包必须成对安装。 只装 ptc-model-check 时，服务器照样能起、探测全绿，但 DSH 里没有 mcp__blender__* 工具——注册它们的是本包的 cordis.patch.yml。完整步骤见 安装文档。

1.2.3 修复真实材质预览的临时补光清理：在临时世界副本上调整环境，完成或失败后恢复原世界、视口着色设置，并移除临时相机和补光数据。配合建模检查插件 2.28.0+ 使用真实材质渲染复核程序纹理。更新后需重新加载 Blender 插件；不要把仅显示材质色的预览当成节点渲染结果。

离线检查：npm test 验证工具通路，python tests/verify_render_cleanup.py 验证补光与世界恢复，不连接活动 Blender。

三个部件

addon/blender_mcp.py   Blender 侧：在 Blender 里开 socket 服务器，执行建模命令
src/server.mjs         MCP 服务器：实现 MCP 协议，把工具暴露给 DSH
cordis.patch.yml       DSH 侧：把 MCP 服务器接进来（mcp__blender__*）

Related MCP server: Blender MCP Server

安装

完整步骤（含 Blender 本体、四层依赖自检、七项验收）见配套插件仓库的 docs/install-blender-mcp.md。这里是最短路径：

0. 把本包装进 DSH profile（这一步才产生 mcp__blender__*）

从 https://github.com/panda472328/dsh-blender-mcp/releases 下载 blender-mcp-1.2.3.zip 解压，然后二选一：

• 让 AI 用 plugin_manager 安装解压目录；

• 手工在 $env:DSH_PROFILE_DIR\package.json 的 dependencies 加 "@local/blender-mcp": "link:<解压目录绝对路径>"，并在 dsh.profile.bundles 数组加 "@local/blender-mcp"，然后在 profile 目录执行 pnpm install。

装完必须完全退出 DSH 再启动（bundle 只在启动时读取，刷新页面无效）。

1. 装 addon

Blender → Edit → Preferences → Add-ons → Install… → 选 addon/blender_mcp.py → 勾选启用。

2. 在 Blender 里启动服务器

3D 视口按 N → 找到「Blender MCP」标签 → 点 Start MCP Server。 默认端口 9876，可在面板里改。

3. 启动 MCP 服务器

node src/server.mjs

默认监听 http://127.0.0.1:8765/mcp。

4. 装进 DSH

plugin_manager({ action: 'install_bundle', target: '<本目录绝对路径>' })

连上后工具会以 mcp__blender__<名字> 出现，例如 mcp__blender__get_scene_info。

命令行参数

node src/server.mjs --port 8765 --blender-port 9876

工具清单（39 个）

场景与查询

创建几何体

编辑几何体

变换与对齐

修改器

材质与贴图

对象管理

观察与渲染

导入导出

其它

调用时机标签

1.2.2 默认使用 script 模式，仅向 AI 暴露 12 个脚本、场景读取、预览与文件工具。几何编辑、材质、UV 和分组由 AI 自主编写 bpy 脚本完成，减少重复工具描述。下面的完整工具目录保留作兼容参考；用 --tool-profile all 或 MCP_TOOL_PROFILE=all 可恢复全部工具，代码没有被删除。更新后需重启 MCP 服务并重新连接，现有进程不会自动切换。

每个工具的描述都以 【何时调用】…【何时不调用】…【做什么】… 开头。这是刻意设计的——MCP 工具的描述会进入模型上下文，写清时机能减少误用。

几条关键规则已经写进服务端的 instructions：

• 优先用 execute_python 自主编写建模和材质脚本；具体工具按需使用

• 脚本内直接命名、建立 Collection、修改器和节点，不强制另调专用工具

• 按逻辑批次查看实际视图，并配合建模检查插件核对数据

• 明确修改范围、支持局部重跑，保留用户原作和有价值的恢复点

• 导出后重开实际文件核对几何与材质

已知限制

实现要点

为什么自己写 MCP 协议：宿主里没有 @modelcontextprotocol/server（它是 devDependency）。MCP 的 Streamable HTTP 传输就是「POST 收 JSON-RPC、回 JSON-RPC」，服务端只需实现 initialize / tools/list / tools/call / ping。手写约 200 行，换来零依赖、可被任意 MCP 客户端使用。

为什么 addon 要区分主线程：bpy.ops 必须在主线程执行。GUI 模式下用 bpy.app.timers 注册一个泵，命令进队列由主线程执行。后台模式没有事件循环，泵不跑，所以：

• 查询类和 bmesh 类操作直接在 socket 线程执行（已改成不依赖 bpy.ops）

• 渲染类明确拒绝（否则进程崩溃，且异常不可捕获）

为什么编辑操作改用 bmesh：bpy.ops.mesh.* 在无界面模式下 poll() 失败（需要 3D 视图区）。改用 bmesh.ops.extrude_face_region / bevel / subdivide_edges / inset_region / bisect_plane 后，GUI 和后台模式都能用。

自测

# addon 全量自测（28 项，不需要 MCP 服务器）
blender -b --python addon/_selftest.py

# MCP 协议层自测
node src/server.mjs --port 8799 &
node -e "..."