setup-polar

Polar セットアップウィザード

プロジェクトで Polar の決済を利用するためのインタラクティブなセットアップガイドです。

セットアップの流れ

以下の手順を順番に進めてください。

ステップ 1：MCP が利用可能か確認する

まず、組織の一覧を取得して Polar MCP サーバーが利用可能か確認します。execute を呼び出して GET /v1/organizations/ を実行するか、サーバーが操作ごとに 1 つのツールを公開している場合は organizations_list を呼び出します。

MCP ツールが動作する場合： ステップ 3 に進みます。

MCP を利用できない場合： ステップ 2 に進みます。

ステップ 2：Polar MCP をインストールする

Polar プラグインがインストール済みの場合： プラグインによって Polar サーバー（polar と、利用可能な場合は polar-sandbox）がすでに設定されています。ユーザーにサインインするよう依頼し、polar-sandbox を優先してください。Claude Code では /mcp、Codex では codex mcp login <server>、Cursor または Antigravity では MCP 設定から、Gemini CLI では /mcp auth <server> を実行します。ChatGPT では、接続を求められたときにサインインします。その後、以下の確認手順に進みます。

それ以外の場合は、ユーザーの環境に応じて Polar MCP サーバーをインストールするよう案内します。

Claude Code：

# Production
claude mcp add --transport http polar https://mcp.polar.sh/mcp/polar-mcp

# Sandbox (recommended for setup)
claude mcp add --transport http polar-sandbox https://mcp.polar.sh/mcp/polar-sandbox

Cursor（.cursor/mcp.json）：

{
  "mcpServers": {
    "polar-sandbox": {
      "url": "https://mcp.polar.sh/mcp/polar-sandbox"
    }
  }
}

その他のクライアントでは、Polar MCP ガイドに従ってください。インストール後、ユーザーにエディターまたは CLI を再起動し、求められたらサインインするよう案内します（Claude Code では /mcp を実行して認証します）。サンドボックスサーバーでは sandbox.polar.sh、本番サーバーでは polar.sh でサインインします。

認証が完了したら、組織の一覧を取得して MCP が動作することを確認します。

ステップ 3：プロジェクトのコンテキストを収集する

ユーザーに次の内容を尋ねます。

1. フレームワーク：どのフレームワークを使用していますか？

   • Next.js（App Router）、Express、Hono、Astro、SvelteKit、Remix、TanStack Start、Nuxt、Fastify、Cloudflare Workers、またはその他の TypeScript／JavaScript フレームワーク
   • Python：統合スキルはありません。Python SDK ドキュメントに従ってください。

2. 環境：サンドボックスと本番のどちらから始めますか？

   • サンドボックス（新規セットアップにおすすめ）
   • 本番

3. 製品の種類：何を販売しますか？

   • サブスクリプション（定期購入）
   • 1 回限りの購入
   • 両方

ここからは、サンドボックスでは polar-sandbox サーバーのツールを、本番では polar サーバーのツールを使用します。polar しか利用できない場合（ChatGPT など）は、サンドボックスダッシュボードまたは Polar CLI を使ってサンドボックス製品を作成します。

ステップ 4：組織を選択する

MCP で組織の一覧を取得します。複数ある場合は、どの組織を使用するかユーザーに尋ねます。その組織の id、slug、default_presentment_currency を控えます。MCP サーバーへのサインイン時に、組織を持たないユーザーには組織の作成がすでに求められています。MCP を利用できない場合は、次の場所で作成できます。

• サンドボックス：https://sandbox.polar.sh/start
• 本番：https://polar.sh/start

ステップ 5：最初の製品を作成する

MCP（POST /v1/products/）で製品を作成します。価格は組織の default_presentment_currency で指定する必要があり、請求間隔は製品ごとに固定です。月額サブスクリプションの例：

{
  "organization_id": "<organization id from Step 4>",
  "name": "Pro Plan",
  "recurring_interval": "month",
  "prices": [{ "amount_type": "fixed", "price_amount": 2900, "price_currency": "<default_presentment_currency>" }]
}

1 回限りの購入の場合は recurring_interval を省略します。「両方」の場合や月払いと年払いの両方を提供する場合は、製品を別々に作成します。サーバー、組織、名前、価格、通貨、請求間隔をユーザーに提示し、確認を得てから製品を作成します。

チェックアウトの連携に使用するため、返された製品 ID を保存します。

ステップ 6：統合コードを生成する

polar-integration スキルに引き継ぎ、ステップ 3 で選択したフレームワーク向けにチェックアウト、カスタマーポータル、Webhook のエンドポイントを生成します。このスキルには、フレームワークに依存しない基本手順と、フレームワークごとのバリエーションが用意されています。

実行する前に、ユーザーが次の環境変数を準備できていることを確認してください（フレームワークが提供する任意のローダーを使用します）。

POLAR_ACCESS_TOKEN=          # organization access token, created below
POLAR_WEBHOOK_SECRET=        # created in Step 7
POLAR_ENVIRONMENT=sandbox    # omit or set to "production" when going live

アクセストークンを作成する最も簡単な方法は Polar CLI です。npm install -g @polar-sh/cli でインストールしてから、ユーザーに次を実行してもらいます。

polar auth login --sandbox
token=$(polar auth token --scope checkouts:write --scope customer_sessions:write) && echo "POLAR_ACCESS_TOKEN=$token" >> .env

polar auth token を実行すると、必要なスコープがあらかじめ選択されたトークンページがブラウザーで開きます。ユーザーがトークンを作成するまで待機し、作成後にトークンを表示するため、トークンを表示せずに .env に保存できます。トークンは現在の組織と環境に紐付いています。polar auth whoami --json で現在の組織と環境を確認でき、polar auth org で変更できます。

CLI を使わない場合は、サンドボックスまたは本番環境のダッシュボードでトークンを作成します：Settings → Access Tokens → Create token。

ステップ 5 の商品 ID を渡して、ステップ 8 でチェックアウトリンクをテストできるようにします。

ステップ 7：Webhook を設定する

開発サーバーを起動し、polar-testing の「ローカルでの Webhook テスト」に従って、Polar CLI で Webhook を開発サーバーに転送します。トンネルもダッシュボードのエンドポイントも必要ありません。

1. ステップ 6 でインストールしていない場合は CLI をインストールし、ユーザーに polar auth login --sandbox を実行してもらいます。ブラウザーが開きます。
2. polar webhook listen --print-secret でローカルの署名シークレットを .env に保存してから、開発サーバーを再起動します。
3. ステップ 6 で生成したルートのパスを使い、バックグラウンドで polar webhook listen <port>/<webhook-path> を起動します。アカウントに複数の組織がある場合は、--org <id from Step 4> を渡します。
4. polar webhook trigger order.paid を実行します。成功時は終了コード 0 になり、Response 2xx の行が表示されます。失敗時はハンドラーのレスポンスが表示され、ステータス 1 で終了します。ハンドラーを修正して、もう一度実行してください。polar webhook listen を実行中のターミナルでイベントが転送されたというメッセージだけが表示される場合は、listen の出力を確認してください。

デプロイ時には、ダッシュボード（Settings → Webhooks）または MCP を使って、公開 URL 用の Webhook エンドポイントを作成します（url、format: "raw"、および events: order.paid、subscription.created、subscription.canceled）。デプロイ環境では、そのエンドポイントのシークレットを POLAR_WEBHOOK_SECRET として設定します。MCP のレスポンスにはシークレットが含まれるため、繰り返し表示せず、ユーザーにはどこからコピーすればよいかを伝えてください。

ステップ 8：統合をテストする

1. ステップ 5 の商品 ID を含むチェックアウト URL にアクセスします（パスとクエリの形式は、ステップ 6 で生成したルートに従います）。
2. テストカード 4242 4242 4242 4242 を使ってチェックアウトを完了します。
3. polar webhook listen に、ハンドラーからの 2xx ステータスとともに order.paid が表示されることを確認します。
4. 成功ページが正しく表示されることを確認します。

ステップ 9：次のステップ

基本的な設定が動作したら、次の項目を提案します。

1. 認証との連携 - チェックアウトを作成する際、ログイン中のユーザーの external_customer_id を渡します。
2. 特典を追加する - ライセンスキー、ファイルのダウンロード、Discord ロールなどを追加します。
3. 本番環境に移行する - 本番環境はサンドボックスとは別です。polar.sh で組織を設定し、商品を再作成して（新しい ID が割り当てられます）、本番用アクセストークンと Webhook エンドポイントを作成し、POLAR_ENVIRONMENT=production を設定します。その後、ダッシュボードで組織を審査に提出します。決済を受け付けられるようになるまで、チェックアウトはブロックされます。