Claude Code 搭配 Blender MCP
连接 Claude Code 与 Blender MCP，检查测试场景并用预览核对修改；执行 Python 前先审查。
核心摘要
“Blender MCP”是一类工具，并非单一官方服务器。应选择仍在维护的仓库，并严格采用其插件、启动器和端口说明。
Claude Code 启动 MCP 服务器，Blender 插件再把工具调用转发到正在运行的 Blender。
处理文件副本，统一对象与集合命名，每次执行一组逻辑修改，检查场景、保存节点，再渲染预览。
任意 Blender Python 可能修改场景、文件、插件和系统可访问资源，执行前必须审查。
可靠做法是：选定一个文档完整的实现，先用可丢弃场景验证本地桥接，只开放当前任务需要的工具，并通过对象状态、保存文件或预览渲染让每次修改都可检查。不要一开始就在重要 .blend 文件上开放任意 Python 执行。
配置 Claude Code 与 Blender MCP
不同 Blender MCP 仓库的命令、端口、鉴权方式和工具名称并不相同。本指南以社区维护的 BlenderMCP 仓库作为具体示例，因为它提供 Blender 插件、通过 uvx 启动的 MCP 服务器、Claude Code 配置、场景检查、视口截图和本地 socket 说明。该项目不隶属于 Blender Foundation，安装前仍应核对仓库中的最新说明。
以本示例为准，需要确认受支持的 Blender 版本、兼容 Python、uv/uvx 和当前 Claude Code。在同一终端运行 uvx --version 与 claude --version。GUI 客户端找不到 uvx 时，应使用完整可执行路径并重新启动客户端。
从所选仓库下载插件文件，通过 Blender Preferences 安装，启用“Interface: Blender MCP”，打开 3D View 侧栏，再从 BlenderMCP 面板建立连接。首次验证使用新场景，不要直接打开正式资产。
在目标项目运行 claude mcp add --transport stdio --scope local blender -- uvx blender-mcp。双横线会把 Claude Code 参数与服务器启动器分开。理解集成方式和权限前，先使用 local 作用域。
Blender 必须保持打开且插件已连接，Claude Code 也要把 blender 服务器显示为正常。修改场景前依次检查 claude mcp list、claude mcp get blender 和会话内 /mcp 面板。
让插件与 MCP 软件包保持同步
该示例项目由 Blender 插件和 MCP 软件包共同组成。升级时应同时更新两端，重新启动 Blender 与 Claude Code，重新连接插件，并先完成一次只读场景检查再继续编辑。版本不一致可能表现为工具缺失、返回格式异常、超时，或调用到达服务器却没有进入 Blender。应在项目记录中写明可用的插件与软件包版本，方便其他机器复现环境。
可靠的场景构建流程
| 步骤 | 主要操作 | 检查重点 | 保护措施 |
|---|---|---|---|
| 定义任务 | 写明文件、单位、允许修改的集合、对象名称、尺寸与交付结果。 | 有顺序的任务约定，并明确禁止事项。 | 不要只给“做得更好”这类模糊指令。 |
| 记录基线 | 修改前读取场景并保存带版本号的副本。 | 集合、对象、当前模式、相机与输出路径。 | 原始文件保持不动。 |
| 分步执行 | 每次只完成几何、材质、灯光或相机中的一类修改。 | 工具返回结果与被修改的对象名称。 | 不要把无关的破坏性操作合并执行。 |
| 结构检查 | 修改后重新读取对象状态。 | 名称、变换、层级、材质、修改器与相机设置。 | 不要把成功提示当成完成证据。 |
| 视觉预览 | 截取视口，或生成低成本预览图。 | 构图、比例、穿插、阴影与可见瑕疵。 | 结构正确并不代表视觉结果合格。 |
| 保存节点 | 只有指定检查通过后才保存或导出。 | 新文件存在、格式正确，且上一版本仍可恢复。 | 覆盖文件或最终导出前要求人工确认。 |
先给 Claude Code 一份场景约定
有效提示词更接近制作任务书，而不是随口提出的要求。应写清起始 .blend 文件、允许 Claude 修改的集合、坐标和单位约定、对象命名、目标尺寸、材质方向、相机构图、输出分辨率，以及本步骤结束时要保存的检查点。同时加入“不得删除现有灯光”“不得应用修改器”“不得覆盖源文件”等禁止条件。信息越明确，歧义越少，也越容易按照 Blender 的对象与集合结构核验结果。
提示词示例：“打开工作副本，先读取场景，报告活动相机以及 Product_Set 集合中的对象。按给定尺寸新增一个名为 Pedestal_A 的对象，不得修改其他集合。完成后报告它的变换与材质槽，截取视口预览，然后停止，不要保存。”
分阶段提高自动化权限
先从只读检查开始，再依次测试创建可删除的基础几何体、修改一个指定对象、添加材质或灯光、生成预览，最后才验证带版本号的保存或导出。每一级都在验证桥接中的不同环节。如果第一次请求就同时包含建模、下载素材、执行 Python、渲染和覆盖文件，失败后很难判断究竟是哪一层出了问题。
结构与画面要分开验收
场景结构检查需要确认对象名称、变换数值、所属集合、修改器顺序、材质槽、相机设置、渲染引擎、分辨率和输出路径；视口截图或预览渲染则用于判断构图、遮挡、表面效果、灯光和明显瑕疵。两类证据都要保留：画面看起来合理，不代表层级和尺寸正确；对象报告完全正确，也可能得到一张不合格的画面。
安全实践与故障排查
始终处理带版本号的副本，保留自动保存，只开放当前任务所需工具。覆盖现有文件、删除集合、安装插件、下载资产或导出最终成果前，都应暂停并要求确认。
示例服务器允许执行任意 Blender Python。此类代码不仅能修改几何体，还会继承 Blender 进程权限，可能访问该进程可用的文件和网络资源。应先阅读生成代码、缩小任务范围，且不要在重要场景上运行来源不明的脚本。
本示例通过本地 socket 连接 MCP 进程与 Blender 插件。其文档中的远程模式可以监听所有网络接口，但没有附加鉴权，因此只能用于可信且隔离的网络，绝不能直接暴露到公网。
如果启用可选的资产或材质服务，应把凭据存入该服务支持的本地配置，不要写进提示词、截图或项目说明。每项服务只授予必要权限，并及时移除停用密钥。
从 Claude Code 一端开始逐层排查
运行 claude mcp list，再查看 claude mcp get blender。检查项目作用域、启动命令、可执行文件路径和服务器启动输出。进程没有成功启动，就不可能连接 Blender 插件。
正常打开 Blender，确认插件已启用，在侧栏面板启动连接，并核对两端的主机和端口一致。任一侧软件包版本变更后，都应重启两个进程。
先报告 Blender 当前模式、选中对象、活动对象与所在集合。许多 Blender 操作依赖上下文；在对象模式下可用的编辑，在编辑模式中可能失败或作用到错误目标。
把请求拆成更小的顺序步骤，每一步完成后重新检查；迭代阶段降低预览分辨率和采样数。发生超时后不要直接重复可能具有破坏性的调用，应先确认 Blender 是否已经执行。
QVeris 在 MCP 工作流中的位置
Blender MCP 负责读取和修改 Blender 内部场景；同一个 Agent 需要调用结构化外部能力时，可以再使用 QVeris。当前 QVeris 目录中没有完全对应的 Blender MCP 工具或供应商条目，因此本页仅提供 QVeris 文档和 演练场，不会把尚未存在的能力描述成一键集成。
- 对象检查、场景修改、视口截图与 Blender 专用执行交给 Blender MCP。
- 只有在目录条目和输入输出约定都明确时，才通过 QVeris 调用补充性的外部 API 或工具。
- 把能力交接写清楚：外部数据导入前先校验，覆盖、发布或最终导出前再由人工确认。
常见问题
不是。“Blender MCP”通常指社区实现。本指南只选择一个文档较完整的仓库作为示例，使用前仍应检查维护者、版本、代码、问题记录与安装说明。
对本示例实现而言必须打开。Claude Code 会启动 MCP 进程，但 Blender 也要保持运行、启用插件并建立连接，场景工具才能工作。
可写工具能够修改已打开场景，但应从带版本号的副本开始，限定可修改集合，并在覆盖任何已有文件前完成检查和人工确认。
如果所选服务器提供相应工具，它可以编排预览或渲染；最终质量仍取决于资产、场景约束、渲染设置和视觉验收。
常见原因是 MCP 进程未启动、注册到了其他作用域、找不到 uvx，或两端版本不一致。先查 Claude Code，再查 Blender 插件连接。
当任务需要来源和结构都已验证的独立外部能力时再使用。实际场景修改仍交给 Blender MCP，外部结果进入场景前先完成校验。