scenario-blender

Blender 场景

概览

Scenario for Blender 是一款适用于 Blender 5.0 及更高版本的开源扩展，采用 GPL-3.0-or-later 许可证，并在其README中标记为实验性。用户可从扩展仓库 https://blender.scenario.com/repo/index.json（Edit > Preferences > Get Extensions > Repositories）或发布页面上的 ZIP 文件安装；手册见 blender.scenario.com。Scenario API 密钥和密钥密码保存在扩展的偏好设置中：Agent 不会接触这些信息。必须启用 Blender 的 Allow Online Access。

该扩展会运行一个本地 MCP 服务 scenario-blender，地址为 http://127.0.0.1:9876/mcp（通过 HTTP POST 传输 JSON-RPC，并使用 bearer token，不支持 SSE）。如果 9876 端口被占用，它会尝试接下来的三个端口，因此应使用 Scenario > Agents (MCP) 中显示的 URL。场景工具会在 Blender 主线程上运行。此处列出的每个工具及其参数均来自扩展的工具参考文档 docs/MCP.md；tools/list 会提供每个工具的完整指导。本地名称采用动词优先格式（list_models、job_status），不可与托管服务的名称（models_list、model_run、jobs_wait）互换。训练、重命名或删除集合、工作流编写和用量查询应在 mcp.scenario.com 上完成：请参阅 scenario 技能；如果任务需要同时使用两个服务，请同时连接。通过 bpy 进行建模、雕刻、绑定或着色属于 scenario-blender-expert 技能的工作；为引擎导出则属于 scenario-blender-export 技能的工作。如果这里提到的某项配套技能不在你可用的技能中，请让用户安装它（npx skills add scenario-labs/skills --skill <name>）；若需无人值守地继续，请依据工具架构进行操作，并指出缺少该技能。

设置

token 会在 Blender 会话中首次启动服务时生成，仅保存在内存中，并且每次重启后都会更改：如果出现 401，说明 token 已过期，请从 Agents (MCP) 面板重新复制设置内容。它是一个秘密，与 API 密钥不同：切勿将它或复制的代码片段粘贴到问题报告、对话记录或截图中。客户端必须在同一台机器上运行，因为 127.0.0.1 是环回地址，并且必须使用该地址：使用其他主机名会返回 403 forbidden host。

Claude Code：

claude mcp add --transport http scenario-blender http://127.0.0.1:9876/mcp \
  --header "Authorization: Bearer <token>"

Codex：

export SCENARIO_BLENDER_TOKEN='<token>'
codex mcp add scenario-blender --url http://127.0.0.1:9876/mcp \
  --bearer-token-env-var SCENARIO_BLENDER_TOKEN

Cursor 使用 mcpServers 条目 "scenario-blender": {"url": "http://127.0.0.1:9876/mcp", "headers": {"Authorization": "Bearer <token>"}}。 Claude Desktop 通过扩展的 stdio 桥接程序连接：从面板复制代码片段，其中会填入已安装的 shim 路径，并确认其命令指向可用的 Python 3 解释器。

启用扩展后以无头模式运行：

export SCENARIO_BLENDER_TOKEN='<token>'
blender --background scene.blend --command scenario_blender --port 9876

--online-mode 会为本次运行启用在线访问。--token '<token>' 会覆盖环境变量，但 token 会暴露在进程参数中；如果两者都未设置，该命令会生成一个 token 并只打印一次。无头模式下，screenshot_viewport、render_still 以及 capture_reference 中除 MESH 以外的所有来源都会失败：这些功能需要图形界面。

快速参考

按调用顺序：

步骤	工具	说明
读取场景	scene_summary、datablocks_summary、object_detail(name)	从这里开始；scene_summary 会报告选中项、摄像机、帧范围和 3D 游标
更改场景	select_objects(names)、set_frame(frame)、camera_path	camera_path 接受 preset（例如 orbit 或 push_in）、自由文本 description 或 waypoints，以及 duration、focal、aim_at_subject；它会为 Render Video 设置场景摄像机动画，不会生成任何内容
查看	screenshot_viewport、render_still(source, width, height)	仅限 GUI；为 Agent 提供 PNG 内容，不会上传
参考	capture_reference(source)，然后调用 reference_upload_status(context_id, reference_id)	source：VIEWPORT、CAMERA、VIEWPORT_CLIP、CAMERA_CLIP 或 MESH（将选中的网格作为一个 GLB）。轮询直到 state 为 imported，然后使用其 asset_id
选择模型	list_models(lane, query)、model_schema(model_id)	通道：image、video、3d、material、audio、render_image、render_video、edit3d、panorama。每次会话都从 list_models 获取 ID，不要使用常量
估价	estimate_cost(model_id, parameters, lane)	免费试运行；返回 quote_id 和 cu_cost_exact（十进制字符串）。lane 默认为 image
生成	generate(lane, model_id, parameters, quote_id, approved_cost)	消耗额度。使用与报价相同的通道、模型和参数；approved_cost 必须是用户批准的准确字符串
等待	wait_for_job(job_id, timeout)、job_status(job_id)	timeout 默认为 45 秒，低于许多客户端采用的 60 秒限制；仅当客户端等待时间更长时才调高至 170。若 delivery_active 为 true，则再次调用
放置	list_local_jobs、prepare_result_application，然后调用 apply_result_application(context_id, application_id)	只有图像结果会自行导入；其他所有结果都要等待获批的目标位置
Python	blender_api_help(path)，然后调用 execute_python(code)	默认关闭，需由用户启用 Allow connected agents to run Python
upload_reference(path, kind) 只会发送用户在本次 Blender 会话中选择的文件，或扩展保存的文件；其他路径都会被拒绝，因此请改为捕获场景，或让用户选择文件。Render Image 和 Render Video 不接受原始参数：先调用 render_form 并设置 action: "configure"，然后设置 action: "prepare" 来捕获并上传场景，接着调用 estimate_cost 和 generate，且省略 parameters。模型会复制捕获内容中的动作，包括四肢动作：对于必须自然行走或奔跑的角色，请将其制作成胶囊体（scenario-blender-blockout）。全景图通过 prepare_result_application 并设置 purpose: "world" 放入 World。

示例：从视口生成位于 3D 游标处的网格

“把我在视口中看到的内容变成旁边的 3D 道具。”

1. 调用 scene_summary：记下 cursor，并确认存在 GUI 会话，因为捕获需要 GUI 会话。
2. 使用 {"source": "VIEWPORT"} 调用 capture_reference，它会返回 context_id 和 reference_id，而不是资产 ID。使用这两个值调用 reference_upload_status，直到 state 为 imported，并保留其 asset_id。上传完成前若场景发生变化，上传会停止。
3. 使用 {"lane": "3d"} 调用 list_models；根据描述选择一个图像转 3D 条目。使用其 model_id 调用 model_schema，以查看图像输入的名称；文件参数使用 Scenario 资产 ID。
4. 使用 {"lane": "3d", "model_id": "<id>", "parameters": {"<image input>": "<asset_id>"}} 调用 estimate_cost，它会返回 quote_id 和 cu_cost_exact。告知用户 CU 成本，并暂停，直到用户同意。在无人应答的无人值守情况下，报告报价并在此停止：没有用户确认，既不能通过此步骤的确认关卡，也不能通过第 8 步的确认关卡。
5. 使用相同的 lane、model_id 和 parameters 调用 generate，并将 quote_id 和 approved_cost 设置为原样的 cu_cost_exact。它会返回 local_id。
6. 使用 {"job_id": "<local_id>"} 调用 wait_for_job（默认等待 45 秒），并再次确认 delivery_active 为 true。3D 通道只会保存结果：此时场景中还没有任何内容。
7. job_status 会列出 import_units；获取 primary 单元的 key。list_local_jobs 会提供 context_id，以及此作业的 request_id 和 revision。
8. 使用 {"context_id": "...", "request_id": "...", "expected_revision": <revision>, "asset_id": "<key>"} 调用 prepare_result_application，以当前 3D 游标作为目标位置进行捕获，并返回 application_id。向用户展示返回的场景、cursor、format 和文件，并等待批准。
9. 使用 context_id 和 application_id 调用 apply_result_application，即可在该游标处导入一个新的模型组。调用 scene_summary 确认结果。

常见错误

• 未先调用最新的 estimate_cost 并获得用户同意就调用 generate。通道、模型、输入、场景或凭据发生变化时，都需要重新报价；每份报价只能使用一次，且估算本身绝不代表已授权消费。
• 重复提交超时的 generate。应改为检查 job_status 或 list_local_jobs；未经确认的提交会阻止相同请求再次提交，直到用户在 Blender 中将其标记为已审核。
• 在文件参数需要资产 ID 的地方传入文件路径或 capture_reference 返回的 reference_id。
• 以为 import_result 会放置结果：它只会说明上述审批流程。
• 在 --background 中执行捕获：只有 capture_reference 的 MESH 可在该模式下工作。
• 假设 execute_python 已启用。默认情况下它处于关闭状态，调用会失败并抛出 PermissionError，错误中会指出 Scenario 偏好设置位置（MCP > 允许已连接的 Agent 运行 Python）：请询问用户，并优先使用专用工具。
• 在此服务上调用托管服务的工具（model_run、jobs_wait、model_schema_get）。
• 将“目录仍在加载中”或“模型描述仍在加载中”视为失败：此时尚未报价、提交或更改任何内容，因此再次调用即可。扩展偏好设置中缺少凭据会导致目录无法加载。
• 假设文件已保存：没有任何工具会保存 .blend 文件，因此请让用户保存。