mcp-culqi

@codespar/mcp-culqi

Culqi 用の MCP サーバー — ペルーの標準的な PSP です。

Culqi はペルーの Stripe とも言える存在で、ペルーの D2C ブランドや SaaS で標準的に利用されています。ホスト型チェックアウトの CulqiOnline、決済リンクの CulqiLink、サブスクリプションの CulqiFull を提供しています。Culqi を追加することで、CodeSpar のカタログにペルーが加わり、メキシコ、ブラジル、コロンビア、アルゼンチン、チリと並びます。

ツール（20）

ツール	目的
create_token	カードをトークン化します（POST /tokens）。
create_charge	課金を作成します（POST /charges）。
get_charge	Culqi ID で課金を取得します。
list_charges	任意のフィルターを指定して課金を一覧表示します（GET /charges）。
capture_charge	事前承認済みの課金を確定します（POST /charges/{id}/capture）。
refund_charge	確定済みの課金を返金します（POST /refunds）。
get_refund	ID で返金を取得します（GET /refunds/{id}）。
create_customer	顧客レコードを作成します（POST /customers）。
get_customer	Culqi ID で顧客を取得します（GET /customers/{id}）。
list_customers	クエリパラメーターとして渡す任意のフィルター（first_name、last_name、email、...）を指定して顧客を一覧表示します（GET /customers）。
create_card	トークン化されたカードを顧客に追加し、再利用できるようにします（POST /cards）。
delete_card	保存済みカードを顧客から削除します（DELETE /cards/{id}）。
create_order	カード以外の決済方法（Yape、PagoEfectivo（現金）、銀行振込）用の注文を作成します（POST /orders）。
confirm_order	未払いの注文を確定します（POST /orders/{id}/confirm）。
list_orders	クエリパラメーターとして渡す任意のフィルター（order_number、state（created、paid、...）を指定して注文を一覧表示します（GET /orders）。
create_plan	サブスクリプションプランを作成します（POST /plans）。
create_subscription	顧客の保存済みカードをプランに登録します（POST /subscriptions）。
cancel_subscription	有効なサブスクリプションを解約します（DELETE /subscriptions/{id}）。
list_events	任意のフィルターを指定して Webhook イベントを一覧表示します（GET /events）。
get_event	ID で単一の Webhook イベントを取得します（GET /events/{id}）。

インストール

npm install @codespar/mcp-culqi

環境

CULQI_SECRET_KEY="sk_test_..."   # or sk_live_... for production

Culqi には独立したサンドボックス URL はありません。キーのプレフィックス（sk_test_ と sk_live_）で環境が選択されます。

認証

すべてのリクエストで Bearer トークンを使用します。

Authorization: Bearer <CULQI_SECRET_KEY>
Content-Type: application/json

ベース URL：https://api.culqi.com/v2。

実行

# stdio (default — for Claude Desktop, Cursor, etc)
npx @codespar/mcp-culqi

# HTTP (for server-to-server testing)
MCP_HTTP=true MCP_PORT=3000 npx @codespar/mcp-culqi

注意事項

• 金額は通貨のセント単位です（例：1000 = S/ 10.00 PEN）。
• 対応通貨：PEN、USD。
• トークン化：カードの生データは通常、クライアント側（culqi.js／モバイル SDK）でトークン化します。create_token ツールは主にテストスクリプト用です。PCI の適用範囲に含まれないバックエンドから、実際の PAN を送信しないでください。
• サブスクリプションの作成時には、tyc: true（利用規約への同意）が必要です。

エンタープライズ

エージェントによる決済にガバナンス、予算上限、監査証跡が必要ですか？ CodeSpar Enterprise は、これらの MCP サーバーにポリシーエンジン、決済ルーティング、コンプライアンステンプレートを追加します。

ライセンス

MIT