UnificAlly MCP

UnificAlly MCP server

UnificAlly API向けのMCP サーバーです。1つのAPIキーで、100種類以上のモデル（Veo 3.1、Kling、Seedance、Hailuo、Grok Imagine、Nano Banana、Flux、GPT Image、Suno、ElevenLabs、Topaz）を通じて、AI アシスタントが動画、画像、音楽、音声、効果音を生成したり、音声を書き起こしたり、メディアをアップスケールしたりできます。

Cursor、Claude Desktop、Claude Code、Cline、Windsurf、Zed、ChatGPT Desktop、Goose、n8n、自作コードなど、あらゆるMCP クライアントで動作します。

インストール

1. https://unifically.com/api-keys でAPIキーを作成します。新しいアカウントには、テスト用に$0.50分の残高が用意されています。
2. クライアントの設定にサーバーを追加します。

{
  "mcpServers": {
    "unifically": {
      "command": "npx",
      "args": ["-y", "@unifically/mcp-server"],
      "env": { "UNIFICALLY_API_KEY": "sk-..." }
    }
  }
}

このブロックは、Cursor（.cursor/mcp.json）、Claude Desktop（claude_desktop_config.json）、Cline、Windsurf（~/.codeium/windsurf/mcp_config.json）でそのまま使用できます。保存後、クライアントを再起動してください。

Claude Code：

claude mcp add unifically -e UNIFICALLY_API_KEY=sk-... -- npx -y @unifically/mcp-server

{
  "context_servers": {
    "unifically": {
      "command": { "path": "npx", "args": ["-y", "@unifically/mcp-server"] },
      "env": { "UNIFICALLY_API_KEY": "sk-..." }
    }
  }
}

UNIFICALLY_API_KEY=sk-... npx -y @unifically/mcp-server

URLを指定できるクライアント向けに、ホスト型サーバーhttps://mcp.unifically.com/mcpも用意されています。リモートサーバーをご覧ください。

例

アシスタントに次のように依頼します。

夕暮れ時の灯台の16:9画像を作成し、続けてその画像から始まる6秒の動画を作成してください。

ツールは次の順に呼び出されます。

{ "name": "generate_image", "arguments": { "prompt": "a lighthouse at dusk, waves, warm light", "aspect_ratio": "16:9" } }

Generated image with google/nano-banana-pro. Result: https://files.unifically.com/image/....png [task_id: 7f3c...]

{ "name": "generate_video", "arguments": { "prompt": "slow push in, waves rolling", "image_url": "https://files.unifically.com/image/....png", "duration": 6 } }

各生成ツールはジョブの完了を待ち、メディアURLを返します。構造化された結果は次のようになります。

{
  task_id: string,
  status: "completed" | "pending" | "processing",
  output: { video_url?, image_url?, audio_url?, image_urls?, audio_urls?, text? },  // when completed
  model: string,
  cost_usd?: number
}

内部では、各呼び出しはUnificAlly APIへの1回のリクエスト（{ model, input }を指定したPOST /v1/tasks、続いてGET /v1/tasks/{id}）であり、APIドキュメントに記載されているものと同じです。

ツール

すべてのツールで、4 つの MCP ヒントがすべて設定されています。残高を消費する 7 つのツールには、destructiveHint: true と idempotentHint: false が設定されているため、読み取り専用ツールを自動承認するクライアントでも、有料実行の前には確認を求めます。生成に失敗しても課金されません。

各モデルのパラメーターと ID、ブラウザー上のプレイグラウンドを確認できます。

• 動画：Veo 3.1、Kling、Seedance、MiniMax Hailuo、Grok Imagine、Wan 3.0、Gemini Omni Flash 1.1
• 画像：Nano Banana、GPT Image 2、Flux.2 Pro、Qwen Image、SeeDream
• 音楽と音声：Suno、ElevenLabs
• アップスケーリング：Topaz Labs

list_modelsは、最新の全カタログを返します。

動作の仕組み

• すべての生成ツールは、prompt のみで動作します。model は任意で、短縮名（veo、kling、flux、nano-banana-2、seedance、tts、sfx、stt）または google/veo-3.1-fast のような完全な ID を指定できます。
• メディアフィールド（image_url、image_urls、end_image_url、reference_image_urls、audio_url、video_url）には、公開された HTTPS URL のみを指定できます。ローカルパスや Base64 文字列を指定すると、最初にアップロードするよう促すエラーが返されます。
• フィールド名はモデルによって異なります（Kling の start_frame_url、Veo の start_image_url、Seedance の first_frame_url）。image_url を渡すと、サーバーが適切な名前に変更します。サーバーに対応するパラメーターがないフィールドは provider_options に指定します。このフィールドを使うとマッピングを上書きすることもできます。
• サーバーは、各モデルで許可される長さ、解像度、アスペクト比を保持しません。API が値をチェックし、修正方法を示す 422 をコストなしで返します。サーバーの指示では、モデルを実行する前に docs.unifically.com/llms.txt にあるモデルのページを読むようアシスタントに伝えます。
• すべての生成ツールは、wait、callback_url、provider_options、confirm_cost も受け付けます。
• エラーは 1 文で返されます。キーがない、または間違っている場合は 401、残高不足の場合は 402（チャージ用リンク付き）、API の検証メッセージ付きで 422 が返されます。タイムアウトの場合は、get_task で再開するようアシスタントに伝えるメッセージが返されます。429、5xx、ネットワークエラーはバックオフを伴って再試行されます。

アップロード

モデルが読み取れるのは公開 URL のみのため、ローカルファイルは最初に UnificAlly CDN へ送信します。

1. upload_file { content_type: "image/png" } は、1 回限りの upload_url と最終的な file_url を返します。アシスタントはシェルに API キーを置かずに、curl でバイトデータを送信します。

   curl -X PUT '<upload_url>' --data-binary @photo.png
   

   URL は署名付きで 1 回のみ使用でき、約 5 分で有効期限が切れます。ファイルは元の品質を保ちます。

2. upload_file { url } は、すでにオンラインにあるファイルを取り込みます。

3. upload_file { file_path } はディスクからファイルを読み込みます。この方法はサーバーが stdio でローカル実行されている場合に限ります。

Base64 でのアップロードには対応していません。また、ユーザーのファイルを別のホストに送信しないよう、指示でアシスタントに伝えます。どちらのルールも実際に起きた失敗を踏まえたものです。Base64 のサイズ上限があると、エージェントが上限に収めるためにユーザーの画像を縮小してしまいました。また、シェルにキーがなかったあるエージェントは、プライベートな写真を公開ファイルホストにアップロードしてしまいました。

長時間かかるジョブ

高品質な動画やフルサイズの楽曲の生成には、数分かかることがあります。

• wait: false は { task_id, status: "pending" } をすぐに返します。status が "completed" になるまで get_task をポーリングします。
• callback_url もすぐに応答し、API は結果を Webhook に POST します。

どのタスクも、後から get_task で再開できます。

支出制限

すべてデフォルトでは無効です。デプロイごとに設定してください。

• UNIFICALLY_CONFIRM_COST_ABOVE=<usd>：この金額を超える料金の呼び出しは見積もりを返し、アシスタントが confirm_cost: true を指定して再試行した場合にのみ実行されます。
• UNIFICALLY_MAX_COST_PER_TASK=<usd>：この金額を超える料金の呼び出しは拒否されます。confirm_cost でこの制限を上書きすることはできません。
• UNIFICALLY_BLOCKED_MODELS=veo-quality,suno または UNIFICALLY_ALLOWED_MODELS=nano-banana-2,flux,tts：実行できるモデルを制限します。
• UNIFICALLY_DISABLE_GENERATION=true：読み取り専用モードです。ブラウジング、dry_run_cost、check_balance は引き続き使用できます。

環境変数

リモートサーバー

MCP_TRANSPORT=http では、/mcp で Streamable HTTP を、GET /sse と POST /messages で従来の SSE を提供します。ホスト版は https://mcp.unifically.com/mcp で動作します。

呼び出し元は各自のキーを送信するため、1 つのデプロイで多くのユーザーにサービスを提供し、各ユーザー自身の残高に請求できます。

1. Authorization: Bearer <key>（推奨）
2. X-API-Key: <key>
3. URL のみを受け付けるクライアントでは ?api_key=<key>。クエリ文字列がプロキシのログに記録されることがあるため、可能な場合はヘッダーを使用してください。

{
  "mcpServers": {
    "unifically": {
      "url": "https://mcp.unifically.com/mcp",
      "headers": { "Authorization": "Bearer sk-..." }
    }
  }
}

claude.ai の場合は、Settings、Connectors、Add custom connector を開き、キーを URL に含めます：https://mcp.unifically.com/mcp?api_key=sk-...。stdio 専用クライアントでは、mcp-remote を使ってブリッジします。

{
  "mcpServers": {
    "unifically": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.unifically.com/mcp", "--header", "Authorization: Bearer sk-..."]
    }
  }
}

HTTP モードの詳細：

• Streamable HTTP はステートレスなので、スティッキーセッションなしで任意のリバースプロキシの背後にスケールできます。
• キーのない呼び出し元は initialize、tools/list、resources/list、prompts/list、ping を実行できるため、レジストリからツール一覧を取得できます。それ以外の操作はすべて 401 を返します。キーなしのトラフィックには IP ごとのレート制限が適用され、同時メッセージ数は 16 件までです。GET /.well-known/mcp-config は、必須設定（api_key）の JSON Schema を返し、GET /.well-known/mcp/server-card.json はツール一覧を返します。
• キーは API で検証され、結果はキャッシュされます。また、IP ごとの予算によって検証失敗が制限されます。レート制限はキーごと、アカウントごとに適用されるため、キーを追加しても 1 つのアカウントの上限は増えません。バッチは 16 メッセージまで、リクエスト本文は 512 KB までです。
• ブラウザーの Origin ヘッダーは DNS リバインディング対策の検証を受けます。MCP クライアントはこのヘッダーを送信しないため、影響を受けません。
• X-Forwarded-For が信頼されるのは、UNIFICALLY_TRUSTED_PROXIES で指定された送信元からの場合のみです。付属の Compose ファイルでは、分離されたネットワーク向けに private が設定されています。共有 LAN では使用しないでください。
• 残高がゼロのキーでも、残高の確認、タスクの一覧表示と取得、ジョブの料金確認はできます。ジョブの開始はできません（402）。
• GET / は接続手順を返し、GET /health は認証不要のヘルスチェックです。

セルフホスト

このリポジトリには、リクエストごとにキーを使用する HTTP トランスポートを実行する Dockerfile と docker-compose.yml が含まれています。コンテナを HTTPS リバースプロキシの背後に配置し、ドメインを割り当てて、ヘルスチェックに /health を使用してください。環境変数の設定は不要です。共有環境へのデプロイでは、UNIFICALLY_CONFIRM_COST_ABOVE=1.00 をデフォルトにするのが適切です。

開発

git clone https://github.com/unifically-dev/unifically-mcp.git
cd unifically-mcp
npm install
cp .env.example .env       # add your UNIFICALLY_API_KEY
npm run dev

ツールを対話形式で確認します。

npx @modelcontextprotocol/inspector npx -y tsx src/index.ts

テスト：

npm test               # build + smoke test
npm run test:vitest    # full suite

トラブルシューティング

リンク

• API ドキュメント：https://docs.unifically.com
• API キー：https://unifically.com/api-keys
• モデル：https://unifically.com/models
• MCP ページ：https://unifically.com/mcp
• サポート：[email protected]、Discord

ライセンス

MIT