blender-mcp-integration

Blender MCP 集成

每项任务开始时，请阅读一次共享执行指南， 了解自主决策、证据节奏和长任务连续性。

使用能改进任务的最精简 MCP 层。

选择层级

如果任务需要实时视口，请检查是否有已连接的 Blender 会话。 如果没有，请提出打开 Blender，并在启动前征求用户同意， 除非用户已在当前对话中授权打开 Blender。 获得授权后，请使用所需资产打开一个单独的会话，连接 Agent Studio Live，然后重试 blender_open_viewport。 保留现有 Blender 会话和未保存的工作；缺少连接只是一个设置步骤， 而不是放弃视口交接的理由。

对于内嵌视口，请使用捆绑的 Agent Studio Live 插件和 blender_open_viewport。它支持刷新、轴向／环绕／缩放导航，以及 点击表面或对象列表条目，以便将精确的场景上下文附加到用户的下一条消息。 在 Blender 中从插件根目录安装 addon/blender_agent_studio_live.py， 启用它，然后在 3D 视图侧栏中按 Connect Agent Studio。它需要交互式 Blender 会话和 GPU 上下文；普通文件工具不受影响。请参阅 实时视口指南。 该桥接不会执行任意 Python，也不会修改几何体。如下所述，通用实时创作 仍可使用单独的集成。

1. 对于常规脚本化构建、检查和渲染，请使用捆绑工具和 Blender CLI。仅当任务需要在受支持版本中与已打开的 Blender 会话实时交互时，才添加 Blender 官方 Lab MCP。
2. 使用 Blender Agent Studio 的 MCP 进行确定性批量检查、标准化几何证据，以及有范围限制的场景渲染。blender_render_scene 会保留相机、灯光、体积和色彩管理，并以内嵌方式返回第一张图像；inspectOnly 会在渲染前发现场景设置。捆绑的 Poly Haven 搜索／下载工具也能获取经过验证的 CC0 纹理和 HDRI，无需其他插件或 API 密钥；有关材质设置和独立 CLI 用法，请参阅渲染工作流。
3. 仅当请求需要其额外的远程主机、Poly Haven、Sketchfab 或外部 3D 生成集成，并且可以接受额外的安装、网络、凭据和遥测范围时，才考虑使用 ahujasid/blender-mcp。
4. 不要在同一主机／端口上运行多个插件套接字服务。

安装或替换 Blender 插件前，请阅读 references/mcp-options.md。

Mixamo 浏览器集成

blender_prepare_mixamo_search 返回的是浏览器搜索 URL 和工作流，而不是 素材库结果。请使用宿主浏览器工具进行实时搜索、预览和下载， 然后使用 blender_import_mixamo_animation 创建新的独立动画 .blend。 Adobe 登录需在浏览器中完成。有关下载设置、本地导入和重定向限制，请参阅动画工作流的 Mixamo 指南。

Pixabay 音效浏览器集成

blender_prepare_pixabay_sound_search 返回的是音效搜索 URL 和 浏览器工作流，而不是实时素材库结果。请使用宿主浏览器工具查看 搜索结果、预览候选音效并下载所选音效。在本地音频文件旁记录其标题、 创作者、时长和来源页面。请根据预期用途查看当前的 Pixabay 内容许可； 请勿将音效作为独立素材重新分发。 Pixabay 的已公开 API涵盖图像和 视频，因此此工具不会使用音频 API，也不会抓取素材库。它不会将音频导入 Blender 场景。

可选场景分析运行时

使用 blender_compare_reference 创建相机匹配的参考图／剪影／叠加图板。它直接通过 Blender 工作，无需 Rust，并以内嵌方式返回图像。经过审核的黑底白色遮罩可选择性地启用投影指标；仅有照片时只能进行视觉比较，不能臆测相似度分数。比较几何体之前，请使用 bpy 或实时 MCP 设置参考相机。

blender_describe_scene、blender_quality_report 和 blender_compare_scenes 使用随附的 Rust SceneIR 分析器。在已安装的插件根目录下，使用稳定版 Rust 工具链运行 bun run setup:runtime，或者将 BAS_RUNTIME_EXECUTABLE 设为兼容的已构建二进制文件。更新后请重新构建。现有工具仍可独立于 Rust 使用。

先获取简洁的场景描述，再查询确切的 objectId 及其后代。边界框使用经过求值的世界坐标几何体。语义角色仅取自已写入的 bas_role 属性。请根据需求说明提供质量约束；地面检查需要命名对象和 groundZ。AABB 关系只是候选关系，并非精确的网格相交结果。请在发现结果中保留返回的限制说明和必需的视觉检查问题。不会生成数值美学评分。

在源级修复后，使用 blender_compare_scenes 比较保留的资产与重新生成的资产。将事实性变更与明确声明的不变量失败分开，并配上相同的视觉证据。如果保留检查不应涵盖已编辑的组件，请使用 invariantObjects。

保持可复现性

• 即使使用实时 MCP 执行，也应将持久模型保存在 Python 源文件中。
• 在执行有风险的任意代码操作之前，先保存新的 .blend 文件。
• 交互迭代时使用官方 MCP 截图。
• 使用 $blender-agent-studio:blender-asset-validation 进行最终的干净进程检查，并设置固定的证据相机。
• 记录基准测试运行中使用了哪些 MCP 工具。

衡量 MCP 的价值

比较：

1. MCP 工具不可用时的插件技能；
2. 启用候选 MCP 后的相同技能。

保持任务、模型、投入、时间预算和评估器一致。统计执行失败、恢复轮次、耗时和最终资产质量。只有当 MCP 依赖能改善结果或显著降低可靠完成任务的成本时，才予以保留。