Magic Hour

Magic Hour MCP サーバー

Magic Hour の画像・動画の生成と編集、音楽生成、アップロード、完了待機、既存のオーディオプロジェクトの取得に対応した OpenAPI ベースの MCP サーバーです。

起動時に、このサーバーは docs/openapi.json を読み込み、FastMCP.from_openapi() で MCP ツールを構築します。OpenAPI 仕様がエンドポイントを網羅し、Magic Hour MCP ポリシーが非同期ポーリング、アップロード、プロジェクトのダウンロードに関するエージェント向けのガイダンスを追加します。

エージェントを接続する

ホスト型作成エンドポイント：https://mcp.magichour.ai/

クライアント設定ガイドに従って、Claude、Claude Code、Codex CLI または ChatGPT を接続してください。接続後、account_retrieve を呼び出して API アクセスを確認し、生成を始める前にアカウントを調べてください。ping だけでは API キーの有効性を確認できません。

お試しください：「私のポートレートを使って、映画のような宇宙飛行士の静止画を作り、ゆっくりとカメラを前進させてアニメーション化してください。顔の一貫性を保ち、レンダリングを待って、完成した動画を表示してください。クレジットを使う前に、アカウントの利用資格と費用を確認してください。」

ツールの手順と出力の確認方法については、workflow_guide_retrieve を使用してください。 コーディング中にドキュメントを検索するには、別の API Docs MCPを使用してください。

ドキュメント：

• Magic Hour エージェントスキル - メディアワークフロー、公開済みの例、復旧ガイダンス
• user.md - ホスト型エンドポイントのユーザーガイド
• integration-handoff.md - FastAPI マウントのチェックリスト
• docs/detailed-step-by-step-integration.md - バックエンド統合の完全ガイド
• docs/api-reference.md - 生成された API リファレンス

有料ワークフローを評価する

ワークロード評価ガイドを使って、入力、モデル、設定、出力、費用など、完了した画像または動画のジョブを比較してください。現在のモデル制限と請求オプションを確認してください。消費したクレジットのドル換算額と、アカウントにチャージする現金は異なります。 たとえば、Creator 年間プランは、144,000 クレジットに対して前払いで 144 ドルかかります。このクレジットで、音声オフ、720p の Kling 3.0 動画（5 秒）を 600 本生成できます（クレジットをすべて使った場合、税抜で 1 本あたり 0.24 ドル）。音声、高解像度、動画参照入力には、より多くのクレジットが必要です。

アカウントの読み取りでは API 認証を確認し、アカウント情報を取得しますが、リクエストごとの料金や利用資格の見積もりは行いません。現在の MCP ツールの契約には、そのような見積もり操作はありません。ワークフローガイドでは、リクエストされたモデル、ソースメディア、またはプランへのアクセスを確認できません。有料プロジェクトを作成する前に、費用やアクセスが不明な点を解決してください。

検証可能な動画の例については、公開済みの画像から動画へのベンチマークで、ソース画像、リクエスト、すべての試行、ダウンロード可能な結果を確認できます。このベンチマークは Magic Hour を通じてモデルを比較するものであり、プロバイダーの品質における優劣や、クリップが人間に受け入れられることを示すものではありません。

クレジットとデータ

MCP による生成では、Magic Hour アカウントのクレジットを使用します。サブスクリプションなしで一回限りのクレジットパックを購入できます。未使用のクレジットは失効しません。パックには、該当する場合、利用規約およびソースコンテンツの権利に従って、ウォーターマークなしの書き出しと商用利用が含まれます。サブスクリプション限定のモデルや解像度へのアクセスは解放されません。

技術的な障害が発生した場合、処理後にクレジットが返還されるのが一般的です。処理が完了したものの結果に満足できない場合、クレジットは自動的には返還されません。待機のタイムアウトはプロジェクトが失敗した証拠ではありません。既存のプロジェクト ID を使って再開してください。支払いの返金には、別途返金ポリシーが適用されます。

信頼とデータ利用では、顧客のプロンプト、アップロード、出力をトレーニングに使用しないという Magic Hour の方針と、機能に応じたデータ保持について説明しています。

セットアップ

pip install -e .

ローカルで実行する

python main.py

ローカル MCP エンドポイント：

http://127.0.0.1:8000/

このローカル開発サーバーは / で実行され、/mcp ではありません。ホストアプリはサーバーをマウントする際に /mcp を追加します。

デフォルトでは、本番環境の Magic Hour API にリクエストを送信します。

https://api.magichour.ai

ツールの検出は公開されています。ツールを呼び出すには認証が必要です。ホスト型の Claude および ChatGPT OAuth コネクターは、サインインしてアクセスを許可するとトークンを処理します。手動でベアラー認証を行うクライアントでは、Magic Hour API キーを含めてください。

Authorization: Bearer <magic_hour_api_key>

エージェントは、次の場所でホストされたサーバーカードを検出できます。

https://mcp.magichour.ai/.well-known/mcp/server-card.json

環境変数：

MAGIC_HOUR_API_BASE_URL=https://api.magichour.ai
MAGIC_HOUR_OPENAPI_PATH=docs/openapi.json
MCP_OAUTH_ISSUER_URL=https://mcp.magichour.ai
MCP_OAUTH_RESOURCE_URL=https://mcp.magichour.ai

MAGIC_HOUR_API_BASE_URL を上書きすると、モックまたは別の API ベースを使用できます。

MAGIC_HOUR_API_BASE_URL=https://api.sideko.dev/v1/mock/magichour/magic-hour/latest python main.py

読み取り専用のワークフローガイダンス

workflow_guide_retrieve は、video-face-swap、image-editor、image-to-video、 video-generator、lip-sync、ugc-ads、talking-photo、または media-apis を受け付けます。入力、製品と API のドキュメント URL、正確な作成ツール名、順序付きの手順、リクエスト例、後続の編集、レビュー基準を返します。API リクエストは行わず、クレジットも消費せず、アカウントへのアクセス権も確認しません。他のツールと同様、既存の認証フローが必要です。

クライアントは、公開されている magic-hour://workflows/index リソースを検出して、magic-hour://workflows/{workflow} を読み込むこともできます。UGC では、準備済みの画像、スクリプト、サポート対象の長さを使用して ai_ugc_ad_create_video を呼び出します。画像の構図調整は別途 Image Editor を呼び出します。返されたプロジェクト ID を保持し、完成したファイルを取得するには wait_for_video_project を使用してください。

たとえば、承認済みの商品写真を直接アニメーション化するために image-to-video を依頼し、完成したクリップを確認して、後の編集にも再利用できます。依頼された見た目に変更が必要な場合、または素材の問題でショットを作成できない場合に限り、静止画を編集してください。talking-photo ガイドでは、ポートレートと既存の音声ファイルが必要です。テキストだけではこのツールを開始できません。ガイドはワークフローを説明するものであり、生成された出力が事前に検証済みであることや、アカウントが利用資格を満たしていることを示すものではありません。

これは、このサーバーに接続するアシスタントがワークフローを選択する際に役立ちます。接続されていない消費者向けアシスタントでの推奨やランキング上の優位性をもたらすものではありません。

OAuth

このサーバーは、OAuth で保護されたリソースのみを提供します。認可サーバーは Magic Hour のウェブアプリ（https://magichour.ai）です。ユーザーはそこでサインインして同意し、アクセス トークンとして Magic Hour API キーを受け取ります。このサーバーはそのキーを API に渡します。本番環境では MCP_OAUTH_ISSUER_URL と MCP_OAUTH_RESOURCE_URL が必要です。docs/future-oauth-support.md を参照してください。

MCP Inspector でテストする

1. サーバーを起動します。
2. 次を実行します。

   npx @modelcontextprotocol/inspector
   

3. Inspector で次を設定します。
   • トランスポート：Streamable HTTP
   • URL：http://127.0.0.1:8000/
   • ヘッダー：Authorization: Bearer <magic_hour_api_key>
4. ping を呼び出します。
5. video_assets_generate_presigned_url または別の生成されたツールを呼び出します。

注：

• FastMCP は、起動時に OpenAPI からエンドポイントツールを生成します。
• 作成ツールは、id と credits_charged をすぐに返します。
• OpenAPI の operationId 値は、説明的な snake_case 形式のツール名に正規化されます。
• 共通の /v1/files/upload-urls エンドポイントの名前は video_assets_generate_presigned_url です。video、audio、image の項目を受け付けます。
• ジョブのポーリングには wait_for_*_project を使用します。exact_download_urls は返されたとおりに使用してください。有効期限のメタデータを追加しないでください。
• 画像と音声の待機ツールは、サポートされている場合、インラインメディアも返します。

cd web && npm ci && npm run build を実行して、MCP App UI を再ビルドし、型チェックします。

ファイルのアップロード

Magic Hour は、ツール引数に生のファイルバイトを含めることを受け付けません。手順は次のとおりです。

1. 生成された共通のアップロード URL 用ツール video_assets_generate_presigned_url を呼び出します
2. 返された upload_url にファイルバイトをアップロードします
3. 返された file_path を生成用ツールに渡します

公開メディア URL を直接指定しても機能する場合がありますが、アップロードした file_path のほうが確実です。呼び出し元または専用のアップロードブリッジからバイトをアップロードしてください。ホスト型 MCP サーバーが、呼び出し元から渡されたローカルファイルシステムのパスを読み取ることはありません。ブラウザチャットには別途、アップロード UI またはブリッジが必要です。docs/future-chat-ui-handoff.md を参照してください。

MCP 音声プリセット

AI Voice Generator が公開および受け付けるのは、mcp_magichour/openapi_policies.py の APPROVED_VOICE_NAMES にある、API の voice_name と完全に一致する文字列のみです。確認済みで承認された汎用／非著名人向けのプリセットをこのタプルに追加すると、次回のデプロイ時にツールが有効になります。既存の上流音声は、安全であると想定されていません。許可リストが空の場合、Voice Generator はツールの検出対象と呼び出し対象から除外されます。Voice Cloner は常に MCP から除外されます。

MCP ポリシーは、起動時と docs/api-reference.md の再生成時に、上流の音声の説明、デフォルト値、例、SDK スニペットを削除します。日次の OpenAPI 同期によって許可リストが拡張されることはありません。MCP の音声を設定するために docs/openapi.json を編集しないでください。このファイルは未変更の上流 API スナップショットのまま維持されます。Magic Hour の主要製品と公開 API に変更はありません。

MCP Meme Generator が公開するのは汎用の Random テンプレートオプションのみであり、著名人向けテンプレート名はスキーマに含まれません。