PopNow API

PopNow Developer MCP Server：Claude Code、Cursor、Codex、自作コードから、あらゆる AI 画像・動画・音声モデルを呼び出す

PopNow Developer MCP Server は、開発者向けのホスト型 Model Context Protocol サーバーです。エンドポイントは https://api.popnow.ai/api/v1/mcp です。PopNow API キーを使って Claude Code、Cursor、Codex、VS Code、または独自の MCP クライアントに追加すると、エージェントは 1 つの接続で画像、動画、音楽、ナレーション音声を生成し、API ID を指定して任意のモデルを実行し、タスクを確認し、エージェントスキルをインストールできます。

ホストするものはありません。有料の呼び出しは、まずすべて USD で見積もられ、承認後にのみAPI 残高に課金されます。キーのモデル許可リスト、IP 許可リスト、支出上限は、PopNow REST APIと同様に適用されます。

このリポジトリには、セットアップガイド、コピーして使えるクライアント設定（examples/）、MCP レジストリマニフェスト、およびローカルサーバーのみを起動するクライアント向けの小型 stdio ブリッジである@popnow/mcpが含まれています。

PopNow アカウントとウェブサイトのクレジットを使って、ChatGPT または Claude アプリ内で PopNow を使いたい場合は、代わりにpopnow-mcpとpopnow.ai/mcpをご利用ください。

目次

• 概要
• クイックスタート
• クライアントを接続する: Claude Code · Cursor · VS Code · Windsurf · Codex · Cline · Claude Desktop と stdio のみ対応するクライアント · その他のクライアント · 自作コードから
• ツール
• USD での見積もりと承認
• 結果と長時間実行ジョブ
• 制限
• 旧アドレスからの移行
• stdio ブリッジ（@popnow/mcp）
• トラブルシューティング
• よくある質問

概要

エンドポイント	https://api.popnow.ai/api/v1/mcp
トランスポート	ステートレスな Streamable HTTP（POST。GET と DELETE は 405 を返します）
認証	API コンソールで取得したキーを使った Authorization: Bearer sk-popnow-...。このエンドポイントでは OAuth サインインを利用できません
課金	API 残高から USD で課金されます。有料の呼び出しはすべて先に見積もりを返し、max_usd が指定された場合のみ実行されます
キーのルール	キーに設定されたモデル許可リスト、IP 許可リスト、日次・月次・累計の支出上限
ツール	メディアツール、任意のモデル ID に対応する create_task、タスク、残高、保存済みレシピ、エージェントスキル（一覧）
サーバー名	popnow-api

クイックスタート

1. API コンソールでAPI キーを作成します。エージェント専用のキーを作成し、1 日あたりの上限を低く設定しておくと便利です。他の連携に影響を与えずに取り消せます。API の残高が $0 の場合は、API のお支払いでチャージしてください。
2. キーを環境に設定します。以下の設定では POPNOW_API_KEY からキーを読み込むため、コミットするファイルにキーを含めずに済みます。

   export POPNOW_API_KEY="sk-popnow-..."
   

3. サーバーを追加します。Claude Code では、次のコマンドを 1 つ実行するだけです。

   claude mcp add --transport http popnow-api https://api.popnow.ai/api/v1/mcp \
     --header "Authorization: Bearer $POPNOW_API_KEY"
   

4. 何かを依頼します。エージェントに画像、動画クリップ、またはサウンドトラックを依頼してください。エージェントが PopNow のツールを選び、USD で価格を表示し、承認後に実行します。

クライアントを接続する

以下の各クライアントは、API キーを使って同じリモートサーバーに接続します。設定済みのファイルは examples/ にあります。

Claude Code

claude mcp add --transport http popnow-api https://api.popnow.ai/api/v1/mcp \
  --header "Authorization: Bearer $POPNOW_API_KEY"

コマンドの実行時にシェルが $POPNOW_API_KEY を展開し、Claude Code はヘッダーをローカルの MCP 設定に保存します。プロジェクトの .mcp.json を使ってサーバーをチームで共有する場合は、代わりに汎用設定を使用してください。Claude Code は各ユーザーの環境から ${POPNOW_API_KEY} を展開します。

Cursor

プロジェクトの .cursor/mcp.json、またはすべてのプロジェクトで使用する場合は ~/.cursor/mcp.json に PopNow を追加します（examples/cursor.mcp.json）。

{
  "mcpServers": {
    "popnow-api": {
      "url": "https://api.popnow.ai/api/v1/mcp",
      "headers": { "Authorization": "Bearer ${env:POPNOW_API_KEY}" }
    }
  }
}

VS Code

VS Code では、最上位のキー名に servers を使用します。この設定ではキーを一度だけ入力し、安全に保存します（examples/vscode.mcp.json）。

{
  "inputs": [
    { "type": "promptString", "id": "popnow-api-key", "description": "PopNow API key (sk-popnow-...)", "password": true }
  ],
  "servers": {
    "popnow-api": {
      "type": "http",
      "url": "https://api.popnow.ai/api/v1/mcp",
      "headers": { "Authorization": "Bearer ${input:popnow-api-key}" }
    }
  }
}

Windsurf

リモートサーバーでは、~/.codeium/windsurf/mcp_config.json で serverUrl を使用します（examples/windsurf.mcp_config.json）。保存後、MCP パネルでRefreshを押してください。

{
  "mcpServers": {
    "popnow-api": {
      "serverUrl": "https://api.popnow.ai/api/v1/mcp",
      "headers": { "Authorization": "Bearer ${env:POPNOW_API_KEY}" }
    }
  }
}

Codex

~/.codex/config.toml を編集します（examples/codex.config.toml）。bearer_token_env_var は環境からキーを読み込みます。

[mcp_servers.popnow-api]
url = "https://api.popnow.ai/api/v1/mcp"
bearer_token_env_var = "POPNOW_API_KEY"

Cline

MCP Servers → Configureを開き、cline_mcp_settings.json に PopNow を追加します。type は明示的に streamableHttp に設定してください。設定しない場合、Cline は従来の SSE トランスポートにフォールバックします（examples/cline_mcp_settings.json）。

{
  "mcpServers": {
    "popnow-api": {
      "type": "streamableHttp",
      "url": "https://api.popnow.ai/api/v1/mcp",
      "headers": { "Authorization": "Bearer sk-popnow-..." },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Claude Desktop と stdio のみをサポートするクライアント

ローカルの stdio サーバーしか起動できないクライアントでは、@popnow/mcp ブリッジを npx で実行できます。バージョン 0.2.0 以降では、デフォルトで開発者エンドポイントに接続します。Claude Desktop では、claude_desktop_config.json（macOS: ~/Library/Application Support/Claude/claude_desktop_config.json、Windows: %APPDATA%\Claude\claude_desktop_config.json）を編集し、アプリを再起動してください（examples/claude-desktop.json）。

{
  "mcpServers": {
    "popnow-api": {
      "command": "npx",
      "args": ["-y", "@popnow/mcp"],
      "env": { "POPNOW_API_KEY": "sk-popnow-..." }
    }
  }
}

ブリッジを実行するには、Node.js 18 以降が必要です。

その他のクライアント

リモート MCP サーバーをサポートするほとんどのクライアントで、この形式を使用できます。Claude Code のプロジェクト用 .mcp.json でも同じ形式を使用します（examples/generic.json）。コミット対象のファイルにキーを貼り付ける前に、クライアントが環境変数をどのように読み込むか確認してください。

{
  "mcpServers": {
    "popnow-api": {
      "type": "http",
      "url": "https://api.popnow.ai/api/v1/mcp",
      "headers": { "Authorization": "Bearer ${POPNOW_API_KEY}" }
    }
  }
}

独自のコードから接続する

公式 Python SDK の場合（pip install mcp）：

import asyncio, os

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    headers = {"Authorization": f"Bearer {os.environ['POPNOW_API_KEY']}"}
    async with streamablehttp_client("https://api.popnow.ai/api/v1/mcp", headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool("check_balance", {})
            for part in result.content:
                print(part.type, getattr(part, "text", ""))

asyncio.run(main())

公式 TypeScript SDK の場合（npm install @modelcontextprotocol/sdk）：

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const transport = new StreamableHTTPClientTransport(new URL('https://api.popnow.ai/api/v1/mcp'), {
  requestInit: { headers: { Authorization: `Bearer ${process.env.POPNOW_API_KEY}` } },
});
const client = new Client({ name: 'my-app', version: '1.0.0' });
await client.connect(transport);

const result = await client.callTool({ name: 'check_balance', arguments: {} });
console.log(result.content[0].text);
await client.close();

または、curl だけを使う方法もあります。サーバーはステートレスなので、各リクエストは独立しています。Accept には両方のメディアタイプを指定してください。この呼び出しは見積もりを取得します。料金はかかりません。

curl -X POST "https://api.popnow.ai/api/v1/mcp" \
  -H "Authorization: Bearer $POPNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "create_task", "arguments": {"model": "google/nano-banana-2.1/text-to-image", "input": {"prompt": "A paper boat on a rainy window sill, soft morning light", "aspect_ratio": "4:5"}}}}'

モデルを直接呼び出す本番コードには、REST APIを使用すると、Webhook、冪等性キー、タスクごとの保持期間など、より細かく制御できます。SDK：Python · JavaScript / TypeScript · Go · Java · PHP。

ツール

標準価格は、デフォルトのモデルと設定を使用した場合の米ドル価格です。有料ツールはすべて、実行前に正確な金額を提示します。パラメーターの完全なリファレンスについては、開発者向け MCP ドキュメントをご覧ください。

ツール	機能	デフォルト	標準価格
create_image	説明文から新しい画像を作成します	Nano Banana 2.1、1K、正方形	約 $0.048
edit_image	スタイル、服装、背景、オブジェクトの追加や削除などを、言葉で写真に指示して変更します	Nano Banana 2.1	約 $0.048
create_video	説明文から短い動画を作成するか、写真に動きを加えます	MiniMax H3、768p、5 秒	約 $0.185
create_music	オリジナルの歌またはインストゥルメンタルを作成します	Suno v6	約 $0.072
create_speech	多様な音声と言語でテキストを読み上げます	Gemini 3.8 Flash TTS、音声 Kore	長さに応じて 1 セント未満
apply_effect	写真をエフェクト動画に変換するか、写真を加工します	エフェクト専用モデル	動画は $0.125～$0.34、写真は $0.03～$0.05
remove_background	被写体を切り抜き、背景透過 PNG にします	Background Remover	$0.0048
upscale	写真や動画を鮮明にし、拡大します	写真は 4K、動画は 1080p	写真は約 $0.012、動画は長さに応じて変動
add_sound	無音動画に合う効果音と環境音を追加します	ツール専用モデル	事前に見積もり
extend_video	動画の最後のフレーム以降を続けて生成します	minimax-h3	事前に見積もり
edit_video	動きを維持しながら、言葉で動画を編集します	kling-o3	事前に見積もり
copy_motion	動画の動きを使ってキャラクター画像をアニメーション化します	kling-3-0	事前に見積もり
create_video_from_references	参照画像の被写体を維持した動画を作成します	minimax-h3	事前に見積もり
transcribe_audio	録音された音声をテキストに変換します	grok-stt	事前に見積もり
create_sound_effects	説明文から効果音、環境音、セリフを作成します	seed-audio-1-0	事前に見積もり
split_layers	画像を編集可能な背景透過 PNG レイヤーに分離します	seedream-5-0-pro	事前に見積もり
erase_object	オブジェクトや人物を削除し、空いた部分を補完します	object-eraser-v1	事前に見積もり
expand_image	写真の端を越えて画像を拡張します	image-expander-v1	事前に見積もり
change_camera_angle	別の視点からシーンを表示します	camera-angle-changer-v1	事前に見積もり
change_pose	参照画像に合わせて人物のポーズを変更します	pose-changer-v1	事前に見積もり
relight_photo	写真の照明を変更します	relight-v1	事前に見積もり
remove_shadow	写真の強い影を取り除きます	shadow-remover-v1	事前に見積もり
anime_to_real	アニメや漫画の画像をフォトリアルな画像に変換します	anime-to-real-v1	事前に見積もり
compose_video	以前の生成結果をつなぎ合わせ、オプションの音楽、ナレーション、字幕、タイトルを加えて完成した MP4 にします		無料
get_job	実行中のタスクを確認し、準備ができたら結果を返します	最大 30 秒待機	無料
list_my_creations	このキーで作成した最近のタスクとリンクを表示します	直近 10 件	無料
check_balance	利用可能な API 残高と実行中のタスク用に確保された資金を米ドルで表示します		無料
list_models	正確な API ID を含む画像、動画、音声モデル、またはすべてのエフェクトを表示します。model を指定すると、そのモデルの入力項目を表示します	画像	無料

model を公開しているツールのみ、list_models のモデルを指定できます。デフォルトを使用する場合は省略してください。すべてのツールは標準の MCP ヒント（readOnlyHint、destructiveHint、openWorldHint）を持ち、削除を行うツールはありません。

開発者向けツール。 このエンドポイントにのみ存在するツールが 4 つあります。

ツール	機能	パラメーター
create_task	REST API の createTask と同様に、モデル固有の input を使って、正確な API モデル ID を指定し、任意のモデルを実行します	model（必須。例：google/nano-banana-2.1/text-to-image）、input、max_usd、currency
get_task	get_job と同じです。タスクを確認して結果を取得します	job_id（必須）、wait_seconds（0〜50、既定値は30）
list_tasks	list_my_creations と同じです。このキーで作成した最近のタスクを一覧表示します	kind（image、video、audio）、limit（1〜20、既定値は10）
install_skill	選択したエージェントスキルです。プレイブック、短時間有効なダウンロードリンク、エージェント向けのインストールコマンドを返します	slug（必須）、agent

category を指定して list_models を呼び出すと、すべてのモデルの正確な ID を確認できます。続けて model を指定して呼び出すと、そのモデルの入力項目を確認できます。create_task は見積もりを提示する前に、モデルのスキーマに照らして input を検証します。そのため、フィールドが不足している場合や不明なフィールドがある場合は、請求されるのではなくメッセージが返されます。

保存済みレシピとスキル。 list_my_recipes、run_my_recipe、get_recipe_run、resume_recipe_run、list_my_skills、use_my_skill を使うと、popnow.ai に保存したレシピ、キャンバスワークフロー、スキルを利用でき、USD での見積もりと承認も同じように行われます。レシピ、ワークフロー、スキルをご覧ください。

エージェントスキル。 find_skills は、リクエストに合ういくつかのエージェントスキルを返します（プレビュー動画、カバー画像、各スキルに必要なもの）。install_skill は、選択したスキルの SKILL.md、数分間有効なパッケージリンク、エージェント向けのインストールコマンド、そのスキルがメディアの作成に使用する PopNow ツールを返します。どちらも無料で、読み取り専用です。その他のスキルについては、popnow-skillsをご覧ください。

USD での見積もりと承認

1. 見積もり。 max_usd を指定せずに有料ツールを呼び出します。処理は開始されず、金額も確保されません。結果には needs_confirmation: true、currency: "USD"、cost_usd、available_usd が含まれます。
2. 承認。 価格をユーザーに提示します。承認後、同じ引数に max_usd を加え、見積もりの cost_usd を設定してツールを再度呼び出します。
3. 実行。 現在の価格が max_usd 以内であれば、タスクが開始されます。価格が上がった場合は、代わりに新しい見積もりが提示され、承認が必要になります。請求は発生しません。

max_usd は、小数点以下最大9桁の非負の10進数を表す文字列です。たとえば "0.012345678" のように指定します。JSON の数値、指数表記、負の値は受け付けられません。currency は省略可能で、USD のみ指定できます。価格がゼロの見積もりを含め、有料の呼び出しにはすべてこの承認が必要です。自動承認のしきい値はありません。

残高が見積もり額に満たない場合、ツールは費用と利用可能額を示す「Not enough API balance」を返し、請求は発生しません。タスクには REST タスクと同じルールが適用されます。タスク開始時に可能な最高額が確保され、実際に使用した分のみが請求されます（確保額を超えることはありません）。タスクが失敗した場合や期限切れになった場合は、確保額が解放されます。同じキーを使って10秒以内に同一の呼び出しを行うと、タスクは1つだけ作成されるため、エージェントが再試行しても二重に支払うことはありません。

You:    Make a 9:16 clip of a vintage car cruising along the coast at golden hour, 10 seconds.
Agent:  (calls create_video → "Needs confirmation, nothing started yet. This costs $0.37 USD; API balance available: $12.40 USD.")
        That's $0.37 from your PopNow API balance. Go ahead?
You:    Yes.
Agent:  (calls create_video again with max_usd: "0.37" → job_id, then get_task)
        Done: coast.mp4. It's in your API logs too.

結果と長時間実行のジョブ

• 画像はプレビューとダウンロードリンクとして返されます。動画と音声はリンクとして返されます。
• ダウンロードリンクには署名が付いており、しばらくすると期限切れになります。各結果には期限切れにならない popnow://g/<job>/<n> リンクも含まれており、別のツールに渡すことができます。そのため、「今すぐこの画像をアニメーション化して」といった指示もそのまま機能します。
• ツールは結果を最大約40秒待ちます。動画は通常それ以上かかるため、応答には job_id が含まれ、エージェントは get_task を呼び出して結果を取得します。
• すべてのタスクは、API コンソールのログに、使用したキー、モデル、USD の金額とともに記録されます。

制限

項目	上限
アカウントごとのツール呼び出し数（get_task のポーリングを含む）	1 分あたり 240 回
アカウントごとの新規タスク数	1 分あたり 20 件
アカウントごとの find_skills / install_skill	1 時間あたり 240 回 / 120 回

上限を超えたタスクには課金されません。ツールに待機する秒数が表示されます。キーの利用上限はすべての呼び出しに適用されます。REST API の制限は別途設定されており、レート制限で説明しています。

古いアドレスからの移行

2026 年 11 月 1 日までは、API キーは https://api.popnow.ai/mcp に接続されていました。このアドレスは 2027 年 1 月 31 日（00:00 UTC） まで API キーを受け付け、同じ開発者向けツールを提供します。すべてのレスポンスには Deprecation、Sunset、Link ヘッダーが含まれます。その後は API キーに対して 401 を返します。

移行するには、MCP 設定の URL を https://api.popnow.ai/api/v1/mcp に変更してください。キー、ツール、USD での課金はそのままです。stdio ブリッジを使用している場合は、@popnow/mcp 0.2.0 以降にアップグレードするか（npx -y @popnow/mcp で自動的に取得されます）、POPNOW_MCP_URL を新しいアドレスに設定してください。

stdio ブリッジ（@popnow/mcp）

packages/popnow-mcp は、ローカルの stdio サーバーしか起動できない MCP クライアント向けの、最小限の TypeScript パッケージ（実行ファイル popnow-mcp）です。公式 MCP SDK の StdioServerTransport を StreamableHTTPClientTransport に接続し、すべてのメッセージを変更せずに転送するため、ツールと価格は常に稼働中のサーバーと一致します。npm では @popnow/mcp として公開されています。設定についてはClaude Desktop と stdio 専用クライアントを参照してください。

環境変数	必須	説明
POPNOW_API_KEY	はい	PopNow API キー（sk-popnow-...）。Bearer トークンとして送信されます
POPNOW_MCP_URL	いいえ	リモートエンドポイント。既定値は https://api.popnow.ai/api/v1/mcp です

ソースからビルドして実行する場合（Node.js 18 以降）：

git clone https://github.com/popnow-ai/popnow-api-mcp.git
cd popnow-api-mcp
npm --prefix packages/popnow-mcp install
npm --prefix packages/popnow-mcp test    # builds with tsc, then runs an end-to-end test against a local fake server
node packages/popnow-mcp/dist/cli.js --help

MCP レジストリマニフェスト

server.json では、MCP レジストリ形式（スキーマ 2025-12-11）に従って、サーバーを io.github.popnow-ai/popnow-api-mcp として記述しています。内容は、Authorization ヘッダーが必須のリモート Streamable HTTP エンドポイントと、@popnow/mcp npm パッケージです。

トラブルシューティング

表示される内容	原因	対処方法
401「This endpoint takes PopNow API keys」	Authorization ヘッダーがないか、API キーではなくサインイン用トークンを使用しています	有効な sk-popnow- キーを使って Authorization: Bearer を送信してください
401「This API key isn't valid」	キーが間違っているか、取り消されているか、期限切れです	API コンソールでキーを作成してください
403 またはキーに関するツールエラー	キーのモデルまたは IP 許可リストによって呼び出しがブロックされています	API コンソールでキーの制限を調整してください
確認が必要です。まだ何も開始されていません	ツールが最初に見積もりを提示しています	承認してから、max_usd を指定して呼び出しを繰り返してください
「Not enough API balance」	API 残高が見積額に足りません	API 請求で入金するか、より安価なモデルまたは短い動画を選んでください
利用上限に関するメッセージ	呼び出しによってキーの上限のいずれかを超える可能性があります	上限を引き上げるか、リセットされるまで待ってください
「Too many creations at once. Nothing was charged.」	1 分間に 20 件を超える新しいタスクを作成しました	メッセージに表示された秒数だけ待ってください
405 Method Not Allowed	エンドポイントに GET または DELETE を送信しています。サーバーはステートレスです	POST を使用してください
Cline は接続するが、何も動作しない	type が指定されていないため、Cline がレガシー SSE を使用しています	"type": "streamableHttp" を設定してください

FAQ

MCP サーバーの利用に追加料金はかかりますか？

いいえ。接続は無料で、list_models、get_task、find_skills などの読み取りツールも無料です。メディアタスクでは、REST API と同じモデル価格で API 残高が消費され、どのタスクも事前に見積もりが提示されます。

API キーではなく OAuth で接続できますか？

いいえ。このエンドポイントで受け付けるのは API キーのみです。そのため、すべての呼び出しは API 残高に請求され、キーの制限と上限が適用されます。PopNow アカウントを使って ChatGPT アプリまたは Claude アプリで PopNow を利用するには、popnow-mcp をご覧ください。

どのモデルを呼び出せますか？

list_models に含まれるすべての画像、動画、音声モデルを利用できます。Kling、Seedance、Wan、Vidu、MiniMax、Nano Banana、GPT Image、Flux、Suno などが含まれます。create_task では、各モデル固有の入力とともに、正確な API ID を指定できます。名前付きツールでは、一般的なタスクに適したデフォルト設定を使って実行できます。

インストールするものはありますか？

いいえ。サーバーはリモートにあるため、アドレスを追加するだけです。ローカルの stdio サーバーしか起動できないクライアントでは、npx -y @popnow/mcp を使ってブリッジを実行できます。

結果はどこに表示されますか？

結果はツールの応答内のリンクとして返されます。すべてのタスクは API コンソールのログにも表示され、list_tasks ではそのキーの最近のタスクを確認できます。

リンク

• Developer MCP：popnow.ai/api/mcp · ドキュメント · API コンソール · API 請求
• REST API：クイックスタート · API リファレンス · モデル
• PopNow のその他の開発者向けリポジトリ：popnow-skills · popnow-cli · popnow-python · popnow-js · popnow-api

コントリビューション

Issue とプルリクエストを歓迎します。CONTRIBUTING.md をご覧ください。セキュリティに関する問題については、SECURITY.md をご覧ください。

ライセンス

MIT © PopNow