Zvid

@zvid/mcp

公式のZvidエージェントおよびMCP サーバーです。Creatorは品質を最優先するワークフローに従います。概要を計画し、デザイン済みの例やライブラリアセットを応用し、プロジェクトのJSONを正確に検証して、レビュー可能なドラフトを保存した後、承認を得てからレンダリングします。AutomationとDeveloperでは、信頼できる直接操作も利用できます。

認証

認証方法は2つだけです。以下のセットアップはいずれかの方法を使用します。

#	方法	対応環境	必要なもの
1	OAuth — Zvidアカウントでサインイン（推奨）	ホスト型エンドポイント https://mcp.zvid.io/mcp	Zvidアカウントと、OAuth対応のStreamable HTTP MCPクライアント。作成または貼り付けが必要なAPIキーはありません。
2	APIキー（zvid_…）	X-Api-Keyヘッダーを使用するホスト型エンドポイント、またはローカルstdio／セルフホスト	app.zvid.io/api-keysで取得したキー。stdioにはNode.js ≥ 18が必要です

方法1 — OAuthサインイン。 https://mcp.zvid.io/mcpをMCPクライアントに追加し、 プロンプトが表示されたらサインインします。エンドポイントはOAuthディスカバリーメタデータを公開し、 単一のスコープzvid:mcpを使った認可コード＋PKCEを使用して、 有効期間の短いアクセストークンと、ローテーションされるリフレッシュトークンを発行します（RFC 7009に基づき失効可能）。 以下のクライアント別手順では、この方法を使用します。

方法2 — APIキー。 app.zvid.io/api-keysでキーを作成し、 次のいずれかの方法で使用します。

• ホスト型： https://mcp.zvid.io/mcpへのX-Api-Keyヘッダーに指定します — OAuthフローを実行できないプログラムクライアントや、従来のアクセス方式に適しています。
• ローカルstdio／セルフホスト： ローカルstdio／セルフホストのセットアップに示すとおり、 ZVID_API_KEY／--api-keyで渡します。 stdioトランスポートはAPIキーのみをサポートします。MCP OAuthはHTTPトランスポート向けに定義されているためです。

ホスト型セットアップ（推奨）

ホスト型エンドポイントはhttps://mcp.zvid.io/mcpです。どちらの認証方法にも対応しています。 OAuthサインイン（方法1 — 以下のクライアント別手順で使用）と、X-Api-Keyヘッダーで指定するAPIキー（方法2）です。

Claude Code

claude mcp add --transport http zvid https://mcp.zvid.io/mcp
claude mcp login zvid

Claude Code内で/mcpを開いて認証することもできます。

OpenAI Codex

サーバーを登録し、MCP設定またはコマンドラインから認証します。

codex mcp add zvid --url https://mcp.zvid.io/mcp
codex mcp login zvid

ダッシュボードには、デフォルトのツールプロファイルと、MCPクライアントのレンダリングごとの最大クレジット数が保存されます。クライアントは、たとえば https://mcp.zvid.io/mcp?profile=creator&maxRenderCredits=60のように、エンドポイントで具体的な値を指定して接続できます。これは接続設定であり、会話中にモデルが変更することはできません。 レンダリングごとのデフォルトのクレジット上限は120です。ダッシュボードで上限を設定した場合、その値は絶対的な上限となります。有効な上限は、ダッシュボードの値とエンドポイントで要求された値のうち、低い方です。

公式のn8nワークフローをダウンロードすると、ダッシュボードのデフォルト値が両方ともワークフローのJSONにコピーされます。各ワークフローでは、ダッシュボードやほかのワークフローを更新せずに、別の具体的なプロファイルとクレジット上限をローカルで選択できます。

ローカル stdio／セルフホスト可能なセットアップ

npm／stdio エントリーポイントでは、API キー（認証方式 2）を使用します。 設定は CLI フラグ、環境変数、~/.zvid-mcp.json の順に解決されます。

npx -y @zvid/mcp --api-key zvid_your_key_here --api-url http://localhost:4000

環境変数	CLI フラグ	必須	デフォルト	用途
ZVID_API_KEY	--api-key zvid_…	stdio のみ	—	Zvid API キー
ZVID_API_URL	--api-url http://…	いいえ	https://api.zvid.io	オーケストレーターのベース URL
ZVID_MCP_PROFILE	--profile creator	いいえ	creator	ツールプロファイル
ZVID_MCP_MAX_RENDER_CREDITS	—	いいえ	120	従来の／フォールバック用ホスト上限。ダッシュボードと明示的に指定された n8n の値が優先されます
ZVID_MCP_MAX_BULK_ITEMS	—	いいえ	25	自動化／開発者向けの一括呼び出しアイテム上限
ZVID_MCP_QUOTE_SECRET	—	ホスト環境	プロセスごとにランダム	複数インスタンスの見積もりに使用する共有 HMAC シークレット

セルフホストの OAuth デプロイでは、両方のサービスでリソースと発行者を同一にしてください。

サービス	変数	本番環境のデフォルト
オーケストレーター	OAUTH_ISSUER	https://api.zvid.io
オーケストレーター	OAUTH_MCP_RESOURCE	https://mcp.zvid.io/mcp
オーケストレーター	OAUTH_CONSENT_URL	https://app.zvid.io/oauth/authorize
MCP	ZVID_MCP_RESOURCE	https://mcp.zvid.io/mcp
MCP	ZVID_OAUTH_ISSUER	https://api.zvid.io

オーケストレーターでは、OAUTH_ACCESS_TOKEN_TTL_SECONDS と OAUTH_REFRESH_TOKEN_TTL_SECONDS も使用できます。デフォルトはそれぞれ 1 時間と 30 日です。

チェックアウトしたリポジトリから実行するには：

cd mcp && npm install && npm run build
claude mcp add zvid --env ZVID_API_KEY=zvid_your_key_here -- node /absolute/path/to/mcp/dist/index.js

デフォルトの Creator ワークフロー

デフォルトの creator プロファイルは、以前の Advanced オーサリング画面に相当します。承認を考慮したドラフトツールに加え、プランニング、デザイン済みのサンプル、クリエイティブライブラリ検索、ストックメディア、スキーマ／ドキュメント、修復、検証、プロジェクト、テンプレートを利用できます。

Creator では、完全なプロジェクト payload を含まない create_media および revise_media の呼び出しは意図的に拒否されます。これにより、モデルの能力が不十分な場合に、概要から質の低いレイアウトを即興で作成してしまうことを防ぎます。エージェントは正確なペイロードを計画、調整、または組み立ててリモートで検証し、すべてのエラーとレイアウト警告を修正してから、ドラフトを保存する必要があります。create_media は引き続きクレジットを消費しません。render_media には引き続き、ユーザーが承認した署名付き見積もりが必要です。

ユーザーが単発の動画や画像ではなく、再利用可能なテンプレートを求めた場合、create_media_template はパラメーター化されたプロジェクト（{{name}} プレースホルダーから参照される安全なデフォルト値を持つトップレベルの variables オブジェクト）を、永続的な tpl_… テンプレートとして保存します。宣言された変数、変更されていないデフォルト値をレンダリングする場合のクレジット見積もり、エディターへのディープリンク（https://editor.zvid.io/?template=<id>）を返します。その後、create_media_from_template は新しい変数値を使って、署名付き見積もりを伴う承認ゲート付きドラフトとしてテンプレートをインスタンス化します。どちらの呼び出しもクレジットを消費しません。creator プロファイルでは、create_media_template に完全なパラメーター化済みペイロードが必要です。これは create_media と同じ仕様です。

レンダリングは、ドラフト作成とは意図的に分離されています。見積もりトークンは HMAC 署名付きで、有効期限は 15 分です。また、ドラフト ID、プロジェクトのバージョン、正規化されたペイロードのハッシュ、メディアタイプ、推定クレジット数に紐付けられ、送信の直前に再検証されます。冪等性 UUID によって、再試行時の重複を防ぎます。

機能プロファイル

プロファイル	想定用途	利用できる機能
readonly	閲覧	get_media、list_media、get_account
creator	ほとんどのユーザー	高品質なオーサリング、ライブラリ、検証、プロジェクト／テンプレート、承認済みレンダリング
automation	信頼されたワークフロー	Creator のツールに加え、直接レンダリング、上限付きの一括レンダリング、Webhook 操作
developer	API のフル開発	登録済みの非破壊ツール／raw ツールすべて

更新ツールと削除ツールは、すべてのプロファイルで無効のままです。保存された Webhook シークレットは get_webhook で伏せ字になり、新しいシークレットを返すのは create_webhook のみです。MCP の一括呼び出しでは通常、最大 25 項目まで処理できますが、アカウントの制限が適用されます。直接 REST API の 500 項目というハード上限によって、このツールの上限が引き上げられることはありません。適切なサイズに分割して処理してください。

サーバーは、ユーザーが呼び出す4つのワークフロープロンプト（商品プロモーション、ソーシャルリール、サムネイル、正方形投稿）と、安全な MCP リソース zvid://authoring/guidelines および zvid://account/summary も公開します。

Creator、Automation、Developer ツール

以下の低レベル機能は、上記のプロファイルでのみ利用できます。

ツール	説明
plan_creative_video	ブリーフに基づく、プランを考慮したストーリーボードとアートディレクションを作成します。さらに libraryCandidates では、ブリーフとの適合度で公開済みのサンプルをランク付けし、適応するか組み立てるかを判断します。consistent、fresh、explore モード、最近のアセットの除外、ブランドトークン、スタイルパック、シーンレシピに対応しています
find_matching_examples	公開済みサンプルのライブラリ全体をブリーフに照らしてランク付けし（カテゴリの類義語、アスペクト比・長さの適合度）、サムネイル付きの候補と、adapt-example、adapt-or-assemble、assemble-similar のいずれかの判断を返します（デザインテンプレート／キャンバスプリセット／シェイプのモジュールを使用）
start_from_example	サンプルのレンダリング可能なプロジェクト JSON と、適応マップ（変数、テキスト／メディアのスロット、シーンの概要、フォント）、適応の契約を取得します。プレミアム向けの方法で、レイアウトを維持したままコピー／メディア／ブランドを差し替えます。プレミアムサンプルがプランでロックされている場合は、無料の代替案を提案します
render_from_example	自動化／開発者向けの直接レンダリングです。サンプルのスラッグと変数値を指定するとテンプレートが保存され、検証後、クレジットを消費するレンダリングがキューに追加されます。クリエイターは create_media_from_example を使用し、その後、承認を得て render_media を実行します
search_creative_library	サンプル、アニメーション付き Design Studio テンプレート、キャンバスプリセット、シェイプを検索します。公開済みの項目では、プレビュー／サムネイルのメタデータも検索結果に含まれます
get_creative_asset	クリエイティブライブラリ内の項目 1 件について、メタデータと完全な JSON コンテンツを取得します
list_stock_providers / search_stock_media	ストックメディアの機能を確認し、Zvid のストックライブラリからレンダリング可能なメディア URL を検索します
get_project_schema	プロジェクトペイロードまたは完全なレンダリングリクエストに対応する、呼び出し元のプランをリアルタイムで考慮した JSON Schema（draft 2020-12）を提供します。検証に関する注記、プロフェッショナル向けの作成ガイドライン、必須のワークフローも含まれます。エンドポイントが利用できない場合は、同梱のデフォルトスキーマにフォールバックします
validate_project_json	レンダリング前にペイロードを検証します。フィールド単位のエラーを無料で確認できます。レイアウトも検査します。テキストの重なり、プリセットによって無視される x/y、キャンバス外のボックス、パディングによる切り抜き、コントラスト不足をチェックします。remote: true を指定すると、プランの実際の制限を使ってライブ API のバリデーターも実行します
list_supported_elements	すべての要素タイプ（IMAGE、VIDEO、GIF、SVG、TEXT、AUDIO、SUBTITLE、SCENE）と必須フィールドを一覧表示します
get_element_docs	要素ごとのドキュメントを表示します。すべてのフィールド、制約、注意点、有効な例が含まれます
get_example_payload	検証済みのペイロード例を提供します。プロモーション動画、テンプレートレンダリング、静止画、字幕、Webhook フローに対応しています
repair_project_json	無効なペイロードを保守的に自動修正し、変更内容をすべて説明します
create_render	プロジェクト JSON（payload）、または template と variables から動画レンダリングをキューに追加します
create_image_render	静止画レンダリング（PNG/JPEG/WebP）をキューに追加します（snapshotTime、quality、transparent に対応）
get_render	ジョブの状態（waiting|active|completed|failed）、進捗、出力 url と thumbnailUrl を返します
list_renders	レンダリングジョブを一覧表示します（type で絞り込み可能）
create_bulk_render	1 つのテンプレート／ペイロード × N 個の変数セットから N 個のジョブを作成します（MCP のデフォルト上限は 25。アカウントの制限も適用されます）
get_bulk_render / list_bulk_renders	一括処理のバッチを確認します
list_templates / get_template	所有するテンプレートを閲覧します。get_template は完全なプロジェクト JSON を返します
create_template / duplicate_template	プランの検証を通過した再利用可能なテンプレートを作成するか、編集可能なアクティブコピーを作成します
preview_template	変数の解決と検証をドライランします。クレジットは消費されません
list_projects / get_project / create_project	エディターの下書きプロジェクトを操作します（https://editor.zvid.io/?project=<id> で開きます）
list_webhooks / create_webhook / get_webhook / test_webhook / list_webhook_deliveries	render.completed / render.failed 用の Webhook エンドポイントです（HMAC-SHA256 署名付き）
get_credits / get_usage_stats	クレジット残高と使用状況を確認します

スキーマを考慮した作成

スキーマツールは、バックエンドの検証と並行して保守され、それと同等であることをテストで確認している共有モジュール（../schema、src/zvidSchema.ts としてベンダー提供）を使用します。get_project_schema は、現在の呼び出し元のプランを考慮するエンドポイントを優先します。live: false とマークされた結果は同梱のフォールバックであり、現在のアカウントの上限を示すものではありません。レンダリング前に、remote: true を指定して validate_project_json を実行し、対象のプロジェクトを正確に検証してください。ローカルスキーマでは、リモートメディアがダウンロードされることや、コンポジションが視覚的に適切であることは確認できません。

サーバーはこのワークフローを MCP の instructions としても公開しているため、準拠したクライアントは初期化時にこれを受け取ります。AI クライアントが動画を作成する場合の、例を起点としたフローは次のとおりです。

1. brief、フォーマット、長さ、ブランド、バリエーションモードを指定して plan_creative_video を実行します。レスポンスには、順位付けされた libraryCandidates と判断結果が含まれます。
2. 判断結果が adapt-example の場合は、start_from_example で例を確認し、新しい変数値を指定して create_media_from_example を実行し、レビュー可能なドラフトを保存してクレジットの見積もりを取得します。タスクで変更が必要な場合を除き、レイアウトとアニメーションを維持してください。対応している変数、条件、反復処理は、インラインプロジェクトでも保存済みテンプレートでも解決されます。保存済みテンプレートは再利用に便利ですが、値の置き換えに必須ではありません。
3. 判断結果が assemble-similar の場合（または確認しても近い例が見つからない場合）は、返された design-templates、canvas-presets、shapes モジュール（または search_creative_library）から、計画したシーンのレシピを組み立てます。関連性のない動画全体のテンプレートを無理に適用しないでください。
4. 各シーンのトピックに合ったビジュアルと音楽には search_stock_media を使用します。src URL はフル品質のものを使用し、サイズはキャンバス以上にしてください。
5. コンポジションを作成する際は、対象の図形に対して get_project_schema ／ list_supported_elements ／ get_element_docs を呼び出します。
6. validate_project_json を実行し（呼び出し元の実際のプランに照らして確認するには remote: true を追加します）、すべてのエラーとレイアウト警告を修正します。機械的な誤りに限り、repair_project_json を使用してください。
7. デフォルトの Creator プロファイルでは、検証済みのペイロードをそのまま create_media で保存します（またはテンプレート／例のドラフトツールを使用します）。ドラフトと見積もりを確認し、必要に応じて修正してから、承認済みの見積もりトークンを指定して render_media を呼び出します。完了するまで get_media または get_render で結果を追跡します。Automation／Developer では、create_render、create_image_render、render_from_example を直接呼び出すと即時に送信され、クレジットが消費されます。これらの呼び出しでは、承認用の事前レンダリングドラフトは作成されません。

静止画や、全体的な計画を伴わない簡単な「X のようなものを作って」というリクエストでは、find_matching_examples から始めます（静止画の場合は type: "image"）。

バリエーションの動作：

• consistent は、再現可能な自動化のために brief から安定したシードを導出します（または variationSeed を受け付けます）。
• fresh は新しい方向性を 1 つ生成します。最近のライブラリアセットは除外することを想定しています。
• explore は、1 つのペイロードの色違いではなく、スタイル／レイアウト／ストーリーボードが実質的に異なる 2 ～ 5 個の方向性を返します。

再利用可能なテンプレートを作成する場合は、最後のレンダリングを create_template に置き換えます。後から get_template で内容を確認し、レンダリング前に preview_template を使い、安全に編集できるコピーを duplicate_template で作成します。更新および削除の変更操作は、意図的に MCP ツールとして公開されていません。

プロンプトの例

• "見出しとBGMを含む、10秒のプロモーション動画用の有効なZvid JSONペイロードを作成してください。"
• "この製品の発売に向けて、実際に異なる9:16のクリエイティブ案を3つ計画してください。最近使われた以下のサンプルスラッグは避けてから、最も優れた案を作成してください。"
• "レンダリング前にこのペイロードを検証し、問題があれば説明してください。"
• "TEXT ビジュアルに必要なフィールドを教えてください。"
• "Zvid がサポートしている字幕アニメーションモードを教えてください。"
• "このペイロードは失敗します。修正して、変更した内容を教えてください。"
• "テンプレート tpl_… から1080pの動画をレンダリングしてください。タイトルは 'Summer Sale' にして、完了したらリンクを教えてください。"
• "これらの変数を使ってテンプレート tpl_… をプレビューし、検証に失敗する項目がないか教えてください。"
• "完了および失敗したレンダリングを通知する、https://example.com/hooks/zvid を送信先とするWebhookを作成してください。"
• "残りのクレジット数と、今月の利用額を教えてください。"

Webhook署名の検証

登録済みWebhookの配信には、X-Zvid-Signature: sha256=<hex> という署名が付与されます。ここで、hex値は HMAC_SHA256(secret, "<X-Zvid-Timestamp>.<raw body>") です。create_webhook が一度だけ返すシークレット（whsec_…）を保存してください。get_webhook ではシークレットが伏字になります。イベントを解析する前に、元のリクエストバイト列を検証してください。

リクエストごとの webhookUrl コールバックには署名がなく、登録済みWebhookのシークレットも共有しません。どちらのコールバックもイベントエンベロープを使用します。正確な本文と検証方法については、Webhookのドキュメントを参照してください。

開発

npm install
npm run build     # tsc → dist/
npm test          # unit + in-memory MCP round-trip tests
# real E2E against a local orchestrator:
ZVID_API_KEY=zvid_… ZVID_API_URL=http://localhost:4000 node scripts/e2e-local.mjs

公開（手動）

確認時点の2026年9月22日には、@zvid/mcp 0.1.0 がnpmで利用可能でした。ホステッドサービスと、インストールしたnpmの特定バージョンでは、異なるリビジョンが公開されている場合があります。接続済みクライアントが実際にサポートする機能を問い合わせてください。

npm。 package.json の version を更新し、mcp/ から npm publish を実行します（公開アクセスは publishConfig で設定されています）。prepublishOnly フックが dist/ をビルドします。

公式MCPレジストリ（registry.modelcontextprotocol.io） — MCP対応クライアントでサーバーを見つけられるように登録します。server.json を読み込みます。io.zvid/* 名前空間の所有権は、zvid.io のDNS TXTレコードで証明します（または、GitHub経由で検証する場合は mcpName／server.json の name を io.github.Zvid-io/zvid-mcp に変更します）。npm publish の後に：

# one-time: install the publisher CLI, then log in (DNS or GitHub)
mcp-publisher login dns --domain zvid.io      # or: mcp-publisher login github
mcp-publisher publish                          # reads ./server.json

リリースごとにバージョンを同期してください。不一致があるとレジストリへの公開がブロックされます。package.json の version、server.json の version、server.json の packages[0].version の3つを一緒に更新します。サーバー名は両方のファイルで一致させる必要があります。package.json の mcpName == server.json の name。

コミュニティとサポート

DiscordのZvidコミュニティに参加して、質問したり、 動画自動化のワークフローについて話し合ったり、作成したものを共有したりできます。 アカウントや請求に関する個別の質問は、https://zvid.io/contact からお問い合わせください。