scenario-blender

Blender のシナリオ

概要

Scenario for Blender は、GPL-3.0-or-later ライセンスのオープンソース拡張機能で、Blender 5.0 以降に対応しています。README では実験的な機能として記載されています。拡張機能リポジトリ https://blender.scenario.com/repo/index.json（編集 > プリファレンス > エクステンションを取得 > リポジトリ）から、またはリリースページにある ZIP からインストールできます。ハンドブックは blender.scenario.com です。Scenario API キーとシークレットは拡張機能のプリファレンスに保存され、エージェントが扱うことはありません。Blender の「オンラインアクセスを許可」は有効にしておく必要があります。

この拡張機能は、http://127.0.0.1:9876/mcp でローカル MCP サーバー scenario-blender を実行します（ベアラートークンを使用した HTTP POST 経由の JSON-RPC で、SSE はありません）。9876 番ポートが使用中の場合は、次の 3 つのポートを順に試します。そのため、使用する URL は Scenario > エージェント（MCP）に表示されるものです。シーンのツールは Blender のメインスレッドで実行されます。ここに記載されているすべてのツールとパラメーターは、拡張機能のツールリファレンス docs/MCP.md に基づいています。tools/list には各ツールの詳細なガイダンスが含まれています。ローカルの名前は動詞で始まる形式（list_models、job_status）で、ホスト型サーバーの名前（models_list、model_run、jobs_wait）とは互換性がありません。トレーニング、コレクションの名前変更や削除、ワークフローの作成と使用は引き続き mcp.scenario.com で行います。scenario スキルを参照し、タスクで両方が必要な場合は両方のサーバーに接続してください。bpy によるモデリング、スカルプト、リギング、シェーディングは scenario-blender-expert スキルの担当です。ここで名前を挙げた関連スキルが利用可能なスキルに含まれていない場合は、インストールするようユーザーに依頼してください（npx skills add scenario-labs/skills --skill <name>）。無人で処理を続ける場合は、ツールスキーマに基づいて作業し、不足している点を明示してください。

セットアップ

トークンは Blender セッションでサーバーが初めて起動したときに生成され、メモリ内にのみ保持されます。再起動のたびに変わるため、401 が返された場合は古いトークンです。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>' は変数を上書きしますが、プロセス引数にトークンが露出します。どちらも指定しない場合、コマンドはトークンを生成し、一度だけ表示します。ヘッドレス実行では、screenshot_viewport、render_still、および MESH 以外のすべての capture_reference ソースが失敗します。これらには GUI が必要です。

クイックリファレンス

呼び出し順：

手順	ツール	備考
シーンを読む	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 専用です。エージェント向けの PNG コンテンツであり、アップロード用ではありません
参照	capture_reference(source)、続けて reference_upload_status(context_id, reference_id)	source：VIEWPORT、CAMERA、VIEWPORT_CLIP、CAMERA_CLIP、または MESH（選択したメッシュを 1 つの GLB として扱います）。state が imported になるまでポーリングし、その後 asset_id を使用します
モデルを選ぶ	list_models(lane, query)、model_schema(model_id)	レーン：image、video、3d、material、audio、render_image、render_video、edit3d、panorama。ID はセッションごとに list_models から取得し、固定値は使いません
見積もる	estimate_cost(model_id, parameters, lane)	無料のドライランです。quote_id と cu_cost_exact（10 進数の文字列）を返します。lane のデフォルトは image です
生成する	generate(lane, model_id, parameters, quote_id, approved_cost)	クレジットを消費します。見積もり時と同じレーン、モデル、パラメーターを使用します。approved_cost は、ユーザーが承認した正確な文字列です
待機する	wait_for_job(job_id, timeout)、job_status(job_id)	timeout は 0～170 秒です。delivery_active が true の間は、再度呼び出してください
配置する	list_local_jobs、prepare_result_application、続けて apply_result_application(context_id, application_id)	Image の結果のみ自動でインポートされます。それ以外は、承認済みの配置先を待ちます
Python	blender_api_help(path)、続けて execute_python(code)	ユーザーが「Allow connected agents to run Python」を有効にするまでオフです
upload_reference(path, kind)が送信するのは、このセッションでユーザーがBlender上で選択したファイル、または拡張機能が保存したファイルだけです。それ以外のパスは拒否されるため、代わりにシーンをキャプチャするか、ユーザーにファイルを選択してもらってください。Render ImageとRender Videoは生のパラメーターを受け取りません。まずaction: "configure"を指定してrender_formを呼び出し、次にaction: "prepare"を指定してシーンをキャプチャ・アップロードし、その後estimate_costとparametersを省略したgenerateを呼び出してください。パノラマをWorldに適用するには、purpose: "world"を指定してprepare_result_applicationを呼び出します。

作業例：ビューポートから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を指定し、さらにquote_idとapproved_costにcu_cost_exactをそのまま設定してgenerateを呼び出します。local_idが返されます。
6. delivery_activeがtrueであることを再度確認し、{"job_id": "<local_id>", "timeout": 170}を指定してwait_for_jobを呼び出します。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を呼び出すと、そのカーソル位置に新しいモデルグループが1つインポートされます。scene_summaryで確認します。

よくある間違い

• 最新のestimate_costとユーザーの承認なしにgenerateを呼び出すこと。レーン、モデル、入力、シーン、認証情報のいずれかが変わった場合は、新しい見積もりが必要です。見積もりは1回しか使えず、見積もりだけで支出が承認されることはありません。
• タイムアウトしたgenerateを再実行すること。代わりにjob_statusまたはlist_local_jobsを確認してください。未確認の送信があると、ユーザーがBlenderで確認済みとマークするまで、同一の送信はブロックされます。
• ファイルパラメーターにアセットIDが必要な箇所に、ファイルパスやcapture_referenceのreference_idを渡すこと。
• import_resultが結果を配置すると期待すること。このツールは、上記の承認フローを説明するだけです。
• --backgroundでキャプチャすること。このモードで動作するのはcapture_referenceのMESHのみです。
• execute_pythonが有効だと思い込むこと。デフォルトでは無効であり、Scenarioの環境設定（MCP > Allow connected agents to run Python）を示すPermissionErrorが発生します。ユーザーに確認し、個別のツールを優先してください。
• このサーバー上でホストサーバーのツール（model_run、jobs_wait、model_schema_get）を呼び出すこと。
• 「カタログをまだ読み込み中」や「モデルの説明をまだ読み込み中」を失敗と見なすこと。見積もりも送信も変更も行われていないため、再度呼び出してください。拡張機能の設定に認証情報がないと、カタログを読み込めません。
• ファイルが保存されていると思い込むこと。.blendを保存するツールはないため、ユーザーに保存を依頼してください。