zen

ZEN MCP

AI アシスタントが ZEN.com Payment Gateway を利用できる MCP サーバーです。ホスト型決済リンク、取引照会、返金、支払い、レポートに対応します。

プロジェクトページ

非公式です。 このプロジェクトは ZEN.com と提携、承認、または保守されていません。

機能

読み取り専用ツール：

• 端末の決済方法と、ドキュメントに記載された通貨を一覧表示します。
• 取引、決済リンク、支払いを照会します。
• 決済リンクを一覧表示し、照合レポートをリクエストします。
• IPN Webhook 署名をローカルで検証します。

書き込みツール：

• カード情報を扱わずに、ホスト型決済リンクと QR コードを作成します。
• 取引を売上確定またはキャンセルし、全額または一部を返金します。
• 支払いと顧客レコードを作成します。

免責事項

この連携は、実際の加盟店アカウントにアクセスせず、公開されている ZEN のドキュメントに基づいて構築されています。本番環境で使用する前に、エンドポイントのバージョン、リクエストフィールド、レスポンスフィールド、署名の詳細、Webhook の動作を ZEN の最新の OpenAPI または Postman コレクションで確認してください。アカウントがなくても評価できるよう、モックモードが含まれています。

インストール

公開パッケージを Claude Code に追加します：

claude mcp add zen --env ZEN_API_KEY=your_terminal_api_key -- npx -y @krystiangw/zen-mcp

Claude Desktop の場合は、MCP 設定に次のエントリを追加します：

{
  "mcpServers": {
    "zen": {
      "command": "npx",
      "args": ["-y", "@krystiangw/zen-mcp"],
      "env": {
        "ZEN_API_KEY": "your_terminal_api_key",
        "ZEN_PAYWALL_SECRET": "your_paywall_secret",
        "ZEN_IPN_SECRET": "your_ipn_secret",
        "ZEN_ENV": "sandbox"
      }
    }
  }
}

設定

変数	必須	説明
ZEN_API_KEY	モックモード以外	Authorization に Bearer プレフィックスなしで送信する端末 API キー
ZEN_PAYWALL_SECRET	書き込み操作	リクエストボディの署名に使うチェックアウト／ペイウォールシークレット
ZEN_IPN_SECRET	Webhook 検証	verify_webhook_signature のみで使用する IPN シークレット
ZEN_ENV	いいえ	sandbox（デフォルト）または production
ZEN_BASE_URL	いいえ	API ベース URL の上書き。ZEN_ENV より優先されます
ZEN_MOCK	いいえ	1 または true にすると、オフラインで決定的なレスポンスを有効にします
ZEN_HASH_ALG	いいえ	sha224、sha256（デフォルト）、sha384、または sha512

ZEN の加盟店パネルで、my.zen.com → Shop settings → Terminal に移動すると、端末 API キーを確認できます。まずは sandbox を使用してください。デフォルトの API ホストは api.zen-test.com ですが、sandbox の利用可否とオンボーディング要件については ZEN に確認してください。

まだ加盟店アカウントをお持ちではありませんか？ZEN ビジネスアカウントを開設できます。これは紹介リンクです。このリンクから登録すると、このプロジェクトの作者に紹介特典が付与されます。費用はかかりません。この README にあるほかのリンクはすべて通常のリンクです。

ツール

名前	種類	説明
list_payment_methods	読み取り	端末の決済方法を一覧表示します
get_transaction	読み取り	ZEN ID または加盟店 ID で取引を取得します
list_payment_links	読み取り	ホスト型決済リンクを一覧表示します
get_payment_link	読み取り	ホスト型決済リンクを1件取得します
get_payout	読み取り	ZEN ID で支払いを取得します
download_report	読み取り	レポートのダウンロードをリクエストします
list_supported_currencies	読み取り	ドキュメントに記載された対応通貨を一覧表示します
verify_webhook_signature	読み取り	ZEN IPN 署名をローカルで検証します
create_payment_link	書き込み	ホスト型チェックアウトリンクと QR コードを作成します
refund_transaction	書き込み、破壊的操作	全額または一部を返金します
capture_transaction	書き込み、破壊的操作	承認済みの取引を売上確定します
cancel_transaction	書き込み、破壊的操作	取引をキャンセルします
create_payout	書き込み、破壊的操作	外部への支払いを実行します
create_customer	書き込み	顧客レコードを作成します

セキュリティ

• ツールはデフォルトで読み取り専用です。資金の移動や返金を行う操作は、MCP クライアント向けに破壊的操作としてマークされています。
• シークレットは環境変数からのみ読み取られ、ツールの引数として渡されることはありません。
• 決済の受け付けには ZEN がホストするリンクを使用するため、このサーバーがカード番号を収集または送信することはありません。
• 署名アルゴリズムは ZEN の公開ドキュメントに従っていますが、ネストされたオブジェクトと配列のフラット化については、公開情報で完全には仕様が定められていません。実際の API で検証してください。
• IPN Webhook の内容を信頼する前に、必ず ZEN_IPN_SECRET で署名を検証してください。
• 最小権限のターミナル認証情報を使用し、書き込みツールでは人間による確認を有効にしてください。

アカウントなしでデモを実行

決定的な定型 API レスポンスを使ってサーバーを実行します。

ZEN_MOCK=1 ZEN_IPN_SECRET=demo npx -y @krystiangw/zen-mcp

verify_webhook_signature は API を呼び出さず、実際の暗号処理を行うため、モックモードでもシークレットが必要です。デモではどのような値でも使用できます。

開発用チェックアウトから実行します。

npm install
npm run build
ZEN_MOCK=1 ZEN_IPN_SECRET=demo npm run inspect

開発

Node.js 18 以降が必要です。

npm install
npm run typecheck
npm run build
npm test
ZEN_MOCK=1 ZEN_IPN_SECRET=demo npm run inspect

ロードマップ

• 生のカード決済は、PCI／セキュリティに関する慎重な設計を行った後にのみ対応します。MVP では対象外です。
• トークン化フローの検証後に、継続決済とワンクリック決済に対応します。
• ZEN がサポート対象の API を公開した場合、キャッシュバックや個人向けカードなど、一般消費者向けの ZEN 機能に対応します。
• stdio 版 MVP の後に、リモート Streamable HTTP トランスポートと OAuth に対応します。

ライセンス

MIT