{
  "markdown": "# paypay-mcp\n\n[![npm version](https://img.shields.io/npm/v/paypay-mcp.svg)](https://www.npmjs.com/package/paypay-mcp)\n[![npm downloads](https://img.shields.io/npm/dm/paypay-mcp.svg)](https://www.npmjs.com/package/paypay-mcp)\n[![MCP Badge](https://lobehub.com/badge/mcp/mrslbt-paypay-mcp)](https://lobehub.com/mcp/mrslbt-paypay-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\nModel Context Protocol server for the [PayPay Open Payment API](https://www.paypay.ne.jp/opa/doc/v1.0/).\n\nWorks with Claude Desktop, Claude Code, Cursor, Windsurf, Zed, ChatGPT Apps SDK, and any other MCP-compatible client. Tool descriptions are provided in English and Japanese.\n\n## Status\n\n`v0.2.x` — production-capable, not yet battle-tested at scale.\n\nThe server runs cleanly against PayPay's production Open Payment API once `PAYPAY_ENV=production` is set with approved merchant credentials. It has not yet processed meaningful real-world volume. If you are routing real payments through it, pin the version and review the source first.\n\n## Tools\n\n| Tool | Description |\n|---|---|\n| `create_qr_code` | Create a dynamic PayPay QR code. Returns the payment URL, deeplink, and a rendered PNG. |\n| `get_payment_details` | Fetch the current status of a payment. |\n| `wait_for_payment` | Poll until a payment reaches a terminal state. |\n| `delete_qr_code` | Invalidate a QR code before payment. |\n| `refund_payment` | Full or partial refund. **Disabled unless `PAYPAY_ENABLE_REFUNDS=true`.** |\n| `cancel_payment` | Cancel a payment when its state is unclear (timeout or error). **Disabled unless `PAYPAY_ENABLE_CANCELS=true`.** |\n\n## Prompts\n\n`accept_single_payment`, `refund_last_payment`, `debug_stuck_payment`.\n\n## Resources\n\n| URI | Description |\n|---|---|\n| `paypay://docs/opa-reference` | Endpoint map, auth scheme, and status vocabulary for the PayPay OPA API. |\n| `paypay://docs/payment-states` | Payment lifecycle and the cancel-vs-refund decision rule. |\n| `paypay://config/current` | Non-secret view of the active config (env, merchantId, baseUrl, transport). |\n\n## Install\n\nOne-click:\n\n[![Install in Cursor](https://img.shields.io/badge/Install-Cursor-0A0A0A?logo=cursor)](cursor://anysphere.cursor-deeplink/mcp/install?name=paypay&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInBheXBheS1tY3AiXX0=)\n[![Install in VS Code](https://img.shields.io/badge/Install-VS_Code-007ACC?logo=visualstudiocode)](https://insiders.vscode.dev/redirect/mcp/install?name=paypay&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22paypay-mcp%22%5D%7D)\n\nOr via npm:\n\n```bash\nnpm install -g paypay-mcp\n```\n\n## Configuration\n\nCredentials come from the [PayPay Developer Dashboard](https://developer.paypay.ne.jp/).\n\n| Variable | Required | Description |\n|---|---|---|\n| `PAYPAY_API_KEY` | yes | OPA API Key ID |\n| `PAYPAY_API_SECRET` | yes | OPA API Key Secret |\n| `PAYPAY_MERCHANT_ID` | yes | Merchant ID |\n| `PAYPAY_ENV` | no | `sandbox` (default) or `production` |\n| `PAYPAY_ENABLE_REFUNDS` | no | Set to `true` to expose `refund_payment`. Disabled by default. |\n| `PAYPAY_ENABLE_CANCELS` | no | Set to `true` to expose `cancel_payment`. Disabled by default. |\n| `MCP_TRANSPORT` | no | `stdio` (default) or `http` |\n| `MCP_HTTP_PORT` | no | Port when `MCP_TRANSPORT=http`. Default `3000`. |\n| `MCP_HTTP_HOST` | no | Bind address. Default `127.0.0.1`. Public binds require `MCP_AUTH_TOKEN`. |\n| `MCP_AUTH_TOKEN` | no | Bearer token required on inbound HTTP requests when set. Mandatory for non-loopback binds. |\n| `MCP_HTTP_ALLOWED_ORIGINS` | no | Comma-separated CORS allowlist. Default: none. |\n\n### Claude Desktop\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"paypay\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"paypay-mcp\"],\n      \"env\": {\n        \"PAYPAY_API_KEY\": \"a_...\",\n        \"PAYPAY_API_SECRET\": \"...\",\n        \"PAYPAY_MERCHANT_ID\": \"...\",\n        \"PAYPAY_ENV\": \"sandbox\"\n      }\n    }\n  }\n}\n```\n\n### Claude Code\n\n```bash\nclaude mcp add paypay -e PAYPAY_API_KEY=... -e PAYPAY_API_SECRET=... -e PAYPAY_MERCHANT_ID=... -- npx -y paypay-mcp\n```\n\n### Cursor\n\nAdd to `~/.cursor/mcp.json` with the same shape as Claude Desktop.\n\n### Remote hosting\n\nRun in HTTP mode. Public binds require `MCP_AUTH_TOKEN`; the server refuses to start otherwise.\n\n```bash\nMCP_TRANSPORT=http \\\n  MCP_HTTP_HOST=0.0.0.0 \\\n  MCP_AUTH_TOKEN=\"$(openssl rand -hex 32)\" \\\n  MCP_HTTP_ALLOWED_ORIGINS=\"https://claude.ai,https://your-app.example.com\" \\\n  PAYPAY_ENV=sandbox \\\n  PAYPAY_API_KEY=... PAYPAY_API_SECRET=... PAYPAY_MERCHANT_ID=... \\\n  npx paypay-mcp\n```\n\nEndpoint: `POST http(s)://<host>:3000/mcp` (Streamable HTTP transport). Clients send `Authorization: Bearer <MCP_AUTH_TOKEN>`. CORS is closed by default.\n\nFor local testing the auth token can be omitted; the server binds to `127.0.0.1` and only accepts loopback connections.\n\n## Environments\n\nSandbox is the default. Production requires PayPay merchant onboarding (business verification and a contract) and must be enabled by explicitly setting `PAYPAY_ENV=production`.\n\n## Constraints\n\n- Amounts are integer JPY.\n- A payment can be canceled until 00:14:59 JST the day after the payment attempt. After that, use a refund.\n- A single order can receive multiple partial refunds, each with a unique `merchantRefundId`, up to the merchant-configured cap.\n- TLS 1.2+ required (Node 20+).\n\n## Development\n\n```bash\ngit clone https://github.com/mrslbt/paypay-mcp.git\ncd paypay-mcp\nnpm install\ncp .env.example .env\nnpm run dev\nnpm test\nnpm run smoke\nnpm run build\n```\n\n## Roadmap\n\nv0.2: PreAuth + Capture, ContinuousPayments, DirectDebit, AccountLink QR, webhook signature verification, reconciliation tools.\n\nv0.3: Native Payment (App Invoke + user JWT auth), Visa-partnership endpoints, OpenTelemetry tracing.\n\n## Safety\n\nThis server can move real money through the PayPay OPA API. Key safeguards:\n\n- **Refund and cancel tools are disabled by default.** `refund_payment` and `cancel_payment` are only registered when `PAYPAY_ENABLE_REFUNDS=true` or `PAYPAY_ENABLE_CANCELS=true`. Only enable them in trusted agent contexts where tool inputs cannot be influenced by untrusted content.\n- **Sandbox is the default.** Production requires an explicit `PAYPAY_ENV=production`, plus completed PayPay merchant onboarding. Always test against sandbox first.\n- **Unique merchantPaymentId and merchantRefundId per call.** PayPay deduplicates by these IDs, so reusing one will either fail or target an older payment. Generate a fresh ID for each new payment or refund.\n- **Tools carry MCP safety annotations.** Read-only tools (`get_payment_details`, `wait_for_payment`) are flagged `readOnlyHint`; money-moving and destructive tools (`refund_payment`, `cancel_payment`, `delete_qr_code`) are flagged `destructiveHint` so compatible clients can warn you before the call. These are advisory hints — the real guard is the gating above.\n\nEven with these gates on, review any money-moving request before approving the tool call. Treat tool inputs derived from model output as untrusted.\n\n## Disclaimer\n\nThis is an unofficial, community-built MCP server. Not affiliated with, endorsed by, or sponsored by PayPay Corporation. PayPay is a registered trademark of its respective owners. Use at your own risk. The author accepts no liability for funds lost through misuse, prompt injection, or bugs.\n\n## License\n\n[MIT](LICENSE)\n",
  "bytes": 7429,
  "sha": "ad16a508f8fef0dde7c1d3ff528b2a2ef2d88f45b41d282df517deaa81c634f1",
  "repo_slug": "mrslbt/paypay-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mrslbt_paypay_mcp_1a2faa0c/readme"
}