paypay-mcp

paypay-mcp

PayPay Open Payment API 用の Model Context Protocol サーバーです。

Claude Desktop、Claude Code、Cursor、Windsurf、Zed、ChatGPT Apps SDK、およびその他の MCP 互換クライアントで動作します。ツールの説明は英語と日本語で提供されています。

ステータス

v0.2.x — 本番環境で利用できる状態ですが、大規模な運用実績はまだありません。

PAYPAY_ENV=production を設定し、承認済みの加盟店認証情報を使用すると、PayPay の本番用 Open Payment API に対してサーバーが正常に動作します。現実の運用で意味のある取引量はまだ処理していません。実際の決済をこのサーバー経由で行う場合は、バージョンを固定し、事前にソースを確認してください。

ツール

ツール	説明
create_qr_code	動的な PayPay QR コードを作成します。決済 URL、ディープリンク、レンダリング済み PNG を返します。
get_payment_details	決済の現在のステータスを取得します。
wait_for_payment	決済が終端状態になるまでポーリングします。
delete_qr_code	決済前に QR コードを無効化します。
refund_payment	全額または一部を返金します。PAYPAY_ENABLE_REFUNDS=true を設定しない限り無効です。
cancel_payment	状態が不明な場合（タイムアウトまたはエラー）に決済をキャンセルします。PAYPAY_ENABLE_CANCELS=true を設定しない限り無効です。

プロンプト

accept_single_payment、refund_last_payment、debug_stuck_payment。

リソース

URI	説明
paypay://docs/opa-reference	PayPay OPA API のエンドポイント一覧、認証方式、ステータスの用語です。
paypay://docs/payment-states	決済のライフサイクルと、キャンセルと返金を選択する際の判断基準です。
paypay://config/current	現在の設定（env、merchantId、baseUrl、transport）の非機密情報を表示します。

インストール

ワンクリック：

または npm 経由：

npm install -g paypay-mcp

設定

認証情報は PayPay Developer Dashboard から取得できます。

変数	必須	説明
PAYPAY_API_KEY	はい	OPA API Key ID
PAYPAY_API_SECRET	はい	OPA API Key Secret
PAYPAY_MERCHANT_ID	はい	Merchant ID
PAYPAY_ENV	いいえ	sandbox（デフォルト）または production
PAYPAY_ENABLE_REFUNDS	いいえ	true に設定すると refund_payment を公開します。デフォルトでは無効です。
PAYPAY_ENABLE_CANCELS	いいえ	true に設定すると cancel_payment を公開します。デフォルトでは無効です。
MCP_TRANSPORT	いいえ	stdio（デフォルト）または http
MCP_HTTP_PORT	いいえ	MCP_TRANSPORT=http の場合のポート。デフォルトは 3000 です。
MCP_HTTP_HOST	いいえ	バインドアドレス。デフォルトは 127.0.0.1 です。パブリックアドレスへのバインドには MCP_AUTH_TOKEN が必要です。
MCP_AUTH_TOKEN	いいえ	設定されている場合、受信 HTTP リクエストに必要なベアラートークンです。ループバック以外へのバインドでは必須です。
MCP_HTTP_ALLOWED_ORIGINS	いいえ	カンマ区切りの CORS 許可リスト。デフォルト：なし。

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json を編集します。

{
  "mcpServers": {
    "paypay": {
      "command": "npx",
      "args": ["-y", "paypay-mcp"],
      "env": {
        "PAYPAY_API_KEY": "a_...",
        "PAYPAY_API_SECRET": "...",
        "PAYPAY_MERCHANT_ID": "...",
        "PAYPAY_ENV": "sandbox"
      }
    }
  }
}

Claude Code

claude mcp add paypay -e PAYPAY_API_KEY=... -e PAYPAY_API_SECRET=... -e PAYPAY_MERCHANT_ID=... -- npx -y paypay-mcp

Cursor

Claude Desktop と同じ形式で ~/.cursor/mcp.json に追加します。

リモートホスティング

HTTP モードで実行します。パブリックバインドには MCP_AUTH_TOKEN が必要です。設定されていない場合、サーバーは起動を拒否します。

MCP_TRANSPORT=http \
  MCP_HTTP_HOST=0.0.0.0 \
  MCP_AUTH_TOKEN="$(openssl rand -hex 32)" \
  MCP_HTTP_ALLOWED_ORIGINS="https://claude.ai,https://your-app.example.com" \
  PAYPAY_ENV=sandbox \
  PAYPAY_API_KEY=... PAYPAY_API_SECRET=... PAYPAY_MERCHANT_ID=... \
  npx paypay-mcp

エンドポイント：POST http(s)://<host>:3000/mcp（Streamable HTTP トランスポート）。クライアントは Authorization: Bearer <MCP_AUTH_TOKEN> を送信します。CORS はデフォルトで無効です。

ローカルテストでは認証トークンを省略できます。その場合、サーバーは 127.0.0.1 にバインドされ、ループバック接続のみを受け付けます。

環境

デフォルトは Sandbox です。Production を利用するには、PayPay の加盟店登録（事業者確認と契約）が必要です。また、PAYPAY_ENV=production を明示的に設定して有効にする必要があります。

制約

• 金額は整数の JPY です。
• 支払いは、支払い試行の翌日 00:14:59 JST までキャンセルできます。それ以降は返金を使用してください。
• 1 件の注文に対して、加盟店が設定した上限まで、固有の merchantRefundId を持つ複数の一部返金を実行できます。
• TLS 1.2 以降が必要です（Node 20 以降）。

開発

git clone https://github.com/mrslbt/paypay-mcp.git
cd paypay-mcp
npm install
cp .env.example .env
npm run dev
npm test
npm run smoke
npm run build

ロードマップ

v0.2：PreAuth + Capture、ContinuousPayments、DirectDebit、AccountLink QR、Webhook 署名検証、照合ツール。

v0.3：Native Payment（App Invoke + ユーザー JWT 認証）、Visa 提携エンドポイント、OpenTelemetry トレーシング。

安全性

このサーバーは PayPay OPA API を介して実際の資金を動かすことができます。主な安全対策は次のとおりです。

• 返金とキャンセルのツールはデフォルトで無効です。 refund_payment と cancel_payment は、PAYPAY_ENABLE_REFUNDS=true または PAYPAY_ENABLE_CANCELS=true の場合にのみ登録されます。ツールの入力が信頼できないコンテンツの影響を受けない、信頼できるエージェントのコンテキストでのみ有効にしてください。
• デフォルトは Sandbox です。 Production の利用には、PAYPAY_ENV=production の明示的な設定と、PayPay の加盟店登録の完了が必要です。必ず最初に Sandbox でテストしてください。
• 呼び出しごとに固有の merchantPaymentId と merchantRefundId を使用してください。 PayPay はこれらの ID で重複を排除するため、同じ ID を再利用すると、処理が失敗するか、以前の支払いが対象になります。新しい支払いや返金ごとに、新しい ID を生成してください。
• ツールには MCP の安全性アノテーションが付いています。 読み取り専用ツール（get_payment_details、wait_for_payment）には readOnlyHint が設定され、資金の移動や破壊的な操作を行うツール（refund_payment、cancel_payment、delete_qr_code）には destructiveHint が設定されているため、対応クライアントは呼び出し前に警告できます。これらは参考情報であり、実際の保護策は上記の有効化条件です。

これらの制限が有効な場合でも、資金を動かすリクエストは、ツール呼び出しを承認する前に必ず確認してください。モデルの出力に由来するツール入力は、信頼できないものとして扱ってください。

免責事項

これは非公式のコミュニティ開発 MCP サーバーです。PayPay Corporation との提携、同社による推奨または後援を受けていません。PayPay は各所有者の登録商標です。ご自身の責任でご利用ください。作者は、誤用、プロンプトインジェクション、またはバグによる資金の損失について一切責任を負いません。

ライセンス

MIT