Kleo

Kleo MCP サーバー

Kleo は、YouTube 動画や Shorts をレンダリングするリモートの Model Context Protocol サーバーです。ユーザーは URL を 1 つ Claude、ChatGPT、Grok、Claude Code、Cursor、VS Code、OpenCode、または Gemini CLI に接続し、ボタンを 1 つ押してログインすると（メールアドレス、パスワード、招待コードは不要です）、動画について自然な言葉で依頼できます。レンダリングは、そのジョブ専用に借りた GPU マシン（Vast.ai）で Keou モーションデザインエンジンを使って実行されます。結果は、7 日間有効な署名付きダウンロードリンク（MP4、.srt 字幕、サムネイル）として返されます。

サーバーはすべて Cloudflare（Workers + KV + D1 + R2 + Workers AI + Cron）の無料プラン上で動作します。本番環境のアドレスは https://mcp.kleooai.com/mcp（Streamable HTTP、OAuth 2.1）です（Worker 自体は https://kleo-mcp.plural-juice.workers.dev/mcp で応答します）。公開サイト（../kleo-site）は、そのアドレスを config.json から読み込みます。

モデル

映画の部分	モデル
動画（映画のすべてのショット）	ByteDance Seedance 2.5、各ショット自身のフレームから動画を生成
フレームとキャラクターシート（ユーザーが写真を提供した場合は、その写真を使用）	Google Nano Banana Pro
画像チェック	撮影を始める前に、ビジョンモデルがすべての画像をユーザーのリクエストと比較します
音楽（リクエストに応じて）	Suno
ナレーション	Kokoro の音声、英語またはイタリア語
仕上げ	4K 60 fps、レンダリング用 GPU でのオプションの AI アップスケーリング（Real-ESRGAN + RIFE）

接続

接続先	方法
Claude（ウェブ／デスクトップ）	Settings → Connectors → Add custom connector → https://mcp.kleooai.com/mcp
Claude Code	claude mcp add --transport http kleo https://mcp.kleooai.com/mcp
ChatGPT	Settings → Connectors → Developer mode → Create → https://mcp.kleooai.com/mcp、OAuth
Cursor / VS Code / OpenCode / Gemini CLI	同じ URL を指定した、kleo という名前の http サーバー
MCP Registry	com.kleooai/kleo（server.json を参照）

ボタンを 1 つ押すだけでログインでき（メールアドレス、パスワードは不要です）、アカウントには 7 クレジットが付与されます。スクリーンショット付きのガイド：https://kleooai.com/connect/

ツール

ツール	機能
kleo_adapt_prompt	最初に呼び出されます。Kleo の受付項目（テーマ、長さ、形式、見た目、対象者、トーン、必須要素）に照らしてリクエストを確認し、リクエストで不明な点について質問します。すべて明らかになったら、トリートメントを書くためのプロデューサーの手法をアシスタントに渡します。
kleo_list_templates	10 種類のテンプレート（形式、長さの範囲、音声、クレジット料金）と、アカウントに残っているクレジットを表示します。
kleo_storyboard_guide	Kleo がレンダリングするストーリーボードの形式（スタイル、シーンの種類、ビート、アイコン、音声、ルール）を例とともに示し、アシスタントがオリジナルのストーリーボードを作成できるようにします。任意です。指定しない場合、Kleo はプロンプトから動画を構成します。
kleo_create_video	テンプレート、プロンプト、（任意の）ストーリーボードからレンダリングをキューに登録します。job_id、eta_min、直ちに請求されるクレジット数を返します。エラーの場合、クレジットは請求されません。
kleo_wait_for_video	呼び出し元のクライアントが許可する時間（ChatGPT／Grok は 45 秒、OpenCode は最大 5 分）だけ待機し、動画の準備ができ次第リンクを返します。これにより、アシスタントはスピナーを表示し続け、独自に結果を届けられます。
kleo_get_job	状態、現在のトラック、進捗率、残り時間を表示します。job_id が指定されていない場合は、アカウントの最近の動画を表示します。
kleo_get_result	完了したジョブの署名付きダウンロードリンクを返します。
kleo_generate_thumbnail	ベータ版ではまだ有効になっていません（すべてのレンダリングにサムネイルが含まれます）。リクエストを記録し、通知を返します。
kleo_cancel_job	キュー登録済みまたは実行中のジョブをキャンセルし、未使用のクレジットを返金します。
kleo_account	残りのクレジットと、アカウントページへの読み取り専用リンク（/credits）を表示します。このリンクはどこに貼り付けても安全です。アカウントを別のブラウザーに引き継ぐ「Kleo key」はアカウントそのものにあたるため、MCP 経由では決して返されません。ユーザーは Kleo Studio（Account → Kleo key）または接続元のブラウザーで /credits を開くと確認できます。

クレジット（src/templates.ts）：1 クレジットは映画 2 秒分に相当し、端数は切り上げ、最低 10 クレジットです。映画はクレジットパックを購入したアカウント向けに制作されます（€5 = 10 クレジット、€15 = 35、€40 = 100。いずれも一回払いで、サブスクリプションではありません）。アニマティック（同じストーリーボードを、描画フレーム上をカメラが動く形式で映像化したもの。生成クリップなし、15～60 秒）は 5 クレジットで、すべてのアカウントが利用できます。新規アカウントに付与される 7 クレジットで 1 本を制作できます。tariffSentence() はすべてのページで引用される説明文です。アカウントは匿名で、メールアドレスもパスワードも不要です。Cookie に保存されるのは HMAC 署名付きハンドル（src/accounts.ts）だけで、これは貼り付け可能な「Kleo key」も兼ねています。D1 テーブル invites は任意のギフト用途としてのみ残されています。サインインページの折りたたまれたフィールドにコードを入力すると、無料分にクレジットが追加されます。不明なコードが入力されても、利用を妨げることはありません。出力：9:16 は 2160×3840、16:9 は 1920×1080、60 fps、H.264 + AAC。ショート動画はマシンの起動を含めて約 10～20 分かかります。長尺動画は長さに比例して時間がかかり、レンダリングに設定されるタイムアウトは、見積もり時の長さ（jobTimeoutMin）に従います。それを下回る一律の時間が設定されることはありません。

ジョブの流れ

client (Claude…) ──OAuth 2.1──▶ /mcp  (src/mcp.ts; login page in src/auth.ts)
                                │  D1: users, credits, gift codes, jobs, audit · KV: OAuth tokens · R2: rendered files
                                │  cron every minute (src/orchestrator.ts):
                                │    1. a storyboard for each queued job (Workers AI, src/storyboard.ts; validated by src/keou-contract.ts)
                                │    2. one Vast.ai instance per job (src/backends/vast.ts, image VAST_IMAGE)
                                │    3. watch running jobs, apply timeouts, purge expired files
                                ▼
                     Vast.ai instance → worker/kleo_worker.py (Keou engine) → uploads → POST /internal/jobs/:id/done → self-destroys
                     Free fallback: a GitHub Actions runner (.github/workflows/render-pool.yml) claims jobs that Vast could not start
                     (POST /internal/pool/claim with POOL_SECRET) and runs the same worker image.

レンダリングバックエンド（RENDER_BACKEND）：vast（本番環境：実際の GPU を使用し、費用がかかります）、mock（プレースホルダーファイルを使った 1 分間のシミュレーションレンダリング。無料です。サーバーはすべてのクライアントにレンダリングがシミュレーションであることを伝えます）、pool（外部ランナーのみ）、manual（手動で起動するコンテナー。test/worker-e2e.mjs で使用）。

ワーカーイメージ

worker/Dockerfile.keou は ghcr.io/tonnooooo/kleo-worker:keou（約 11 GB：Keou エンジン、Chromium、Node、ffmpeg、Kokoro 音声、faster-whisper）をビルドします。GitHub Actions（.github/workflows/worker-image.yml）は、worker/ に変更を含む main へのプッシュごとに、または Actions タブから手動で、このイメージをビルドしてプッシュします。Vast.ai マシンがパッケージをプルできるように、ghcr.io でパブリックのままにしておく必要があります。詳細：worker/README-keou.md。

ローカル開発

npm install
npm run db:migrate:local
npm run dev                # http://localhost:8787 with .dev.vars: simulated renders, no GPU, bundled storyboard (STORYBOARD_FIXTURE=example)

Claude Code をローカルサーバーに接続します：claude mcp add --transport http kleo-local http://localhost:8787/mcp を実行し、次に /mcp → Kleo → Authenticate を選んでボタンを押します。入力するものはありません。

テスト

npm run test:smoke                                                  # starts its own wrangler dev on port 8799: OAuth, tools, queue, simulated render, signed download, cancel + refund
node --test test/keou-contract.test.mjs test/storyboard.test.mjs    # unit tests: storyboard validator and generator (offline, fake AI)
node --test test/accounts.test.mjs test/credits.test.mjs            # sign-in, signed handles, free credits, daily caps, credit lifecycle (offline, sqlite)
node test/worker-e2e.mjs                                            # real Keou render inside the container (podman, no GPU) against a local server in manual mode
node test/vast-e2e.mjs                                              # one real 20 s job on Vast.ai: costs a few cents, see the file header for the setup
npm run typecheck

デプロイ

必要なものはすべてプロビジョニング済みです：npm run deploy を実行すると wrangler.jsonc が公開されます（すべての変数について、1 行のコメントで説明されています）。初回セットアップ、シークレット、オーナー向けのステップごとのガイド（イタリア語）：DEPLOY.md。シークレット：INTERNAL_SECRET、VAST_API_KEY（設定済み）；POOL_SECRET（プールのフォールバック）；RESEND_API_KEY + NOTIFY_FROM（メール通知用。未設定のため、現在 notify_email は何もしません）；TURNSTILE_SECRET（未設定のため、サインインページのボットチェックはスキップされます）。INTERNAL_SECRET は絶対にローテーションしないでください：アカウントハンドルとダウンロードリンクの両方に署名しているため、新しい値にするとすべてのユーザーがクレジットから切り離されます。

無料デモ用に GPU を停止するには、wrangler.jsonc の RENDER_BACKEND を mock に設定してデプロイします。デプロイせずに今すぐ支出を止めるには、Authorization: Bearer <INTERNAL_SECRET> を指定して POST /internal/admin/pause を実行します（再開するには /internal/admin/resume）。DEPLOY.md のセクション 5 を参照してください。

安全策

ジョブがキューに入るとクレジットが差し引かれ、失敗またはキャンセル時に返金されます。アカウントごとの未完了ジョブ数は最大 MAX_JOBS_PER_USER、全体のインスタンス数は最大 MAX_CONCURRENT_GPUS です。各ジョブには厳格な JOB_TIMEOUT_MIN が設定されており、時間が経過するとインスタンスが破棄されます。また、レンタル後 START_TIMEOUT_MIN の間応答がないマシンは破棄され、ジョブがキューに戻されます。ワーカーは独自のウォッチドッグを備えており、Vast の制限付き CONTAINER_API_KEY を使ってインスタンスを破棄します。「クレジットなし／オファーなし」という応答の後は、VAST_RETRY_MIN の間 Vast に再試行しません。ダウンロードリンクには HMAC 署名が付与され、ファイルと同時に期限切れになります。プロンプトフィルターは、GPU の費用が発生する前に禁止コンテンツをブロックします。

これらすべての上位に DAILY_GPU_BUDGET_USD があります。何かをレンタルする前に、オーケストレーターは今日のレンタル費用（完了、失敗、キャンセルを問わず、マシンが破棄されるたびに cost_usd が記録されます）に、現在稼働中の有料マシンがすでに確保している費用（各マシンのタイムアウト時間に対して VAST_MAX_DPH で算出されます。無料プールのジョブは費用を確保しません）を加算します。上限を超えると、ジョブをキュー内の順序のまま維持しながら、レンタルを 1 時間停止します。この数値はあくまで推定です。価格上限は上限値であり、実際の金額は Vast.ai の残高です。新規アカウントには、1 日あたりの上限（MAX_NEW_USERS_PER_DAY）とアドレスごとの 1 日あたりの上限（アドレスそのものではなく、アドレスのハッシュを使う MAX_NEW_USERS_PER_IP_DAY）があります。アカウントごとの 1 日あたりのジョブ数にも上限があり（返金されなかったジョブのみを数える MAX_JOBS_PER_DAY）、アドレスごとの 1 分あたりのサインイン試行回数にも上限があります（アドレスそのものではなく、アドレスのハッシュをキーにするレート制限バインディング SIGNUP_LIMIT）。すべての制限は Worker 内で /authorize に対してのみ適用されます。/mcp の前には適用しません。ここで 403 または 429 が返ると、アプリケーションがリクエストを受け取る前にコネクターが動作しなくなります。

ドキュメント

• DEPLOY.md — 現在の状況、公開手順、日常の運用（イタリア語）
• docs/MCP-GUIDA.md — MCP とは何か、各クライアントの接続方法、7 つのツール（イタリア語）
• docs/ARCHITETTURA.md — 当初の実現可能性分析とアーキテクチャ（イタリア語）