mcp-celcoin

@codespar/mcp-celcoin

Celcoin 用の MCP サーバー — Pix、boleto、振込、チャージに対応する BaaS インフラストラクチャ

クイックスタート

Claude Desktop

~/.config/claude/claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "celcoin": {
      "command": "npx",
      "args": ["-y", "@codespar/mcp-celcoin"],
      "env": {
        "CELCOIN_CLIENT_ID": "your-client-id",
        "CELCOIN_CLIENT_SECRET": "your-client-secret",
        "CELCOIN_SANDBOX": "true"
      }
    }
  }
}

Claude Code

claude mcp add celcoin -- npx @codespar/mcp-celcoin

Cursor / VS Code

.cursor/mcp.json または .vscode/mcp.json に追加します：

{
  "servers": {
    "celcoin": {
      "command": "npx",
      "args": ["-y", "@codespar/mcp-celcoin"],
      "env": {
        "CELCOIN_CLIENT_ID": "your-client-id",
        "CELCOIN_CLIENT_SECRET": "your-client-secret",
        "CELCOIN_SANDBOX": "true"
      }
    }
  }
}

ツール（18）

ツール	目的
create_pix_payment	Celcoin 経由で Pix 決済を作成します
get_pix_payment	トランザクション ID で Pix 決済の詳細を取得します
create_pix_cob	Pix の即時請求（cob）を作成します — 支払人向けの QR コード／コピー＆ペースト用コードを生成します
get_pix_cob	transactionId または txid で Pix の即時請求を取得します
create_pix_cobv	Pix の期日指定請求（cobv）を作成します — 期日付きの boleto のような Pix です
lookup_pix_dict	Pix DICT キーを照会します — Pix キーから口座名義人と銀行情報を特定します
create_pix_devolution	Pix の返金（devolução）を作成します — 受け取った Pix トランザクションを返金します
cancel_boleto	請求書発行製品で発行された boleto を ID でキャンセルします
read_barcode	支払い前に boleto／公共料金のバーコードを承認（照会）します — transactionId、金額、更新後の合計額、期日を返します
pay_bill	事前に承認された請求書の支払いを確定します — read_barcode の transactionId を transactionIdAuthorize として渡します
get_statement	指定した期間の口座明細（extrato）を取得します
list_topup_providers	チャージに利用できる通信事業者（operadoras）を一覧表示します
create_boleto	請求書発行製品で boleto を発行します
get_boleto	発行済み boleto の詳細を ID で取得します
create_transfer	Celcoin 経由で銀行振込（TED/DOC）を作成します
get_balance	Celcoin の口座残高を取得します
list_banks	ブラジルで利用可能な銀行（ISPB コード）を一覧表示します
create_topup	Celcoin 経由で携帯電話／サービスのチャージ（recarga）を作成します

認証

Celcoin は OAuth2 クライアントクレデンシャルを使用します。サーバーはトークンの更新を自動的に管理します。

サンドボックス／テスト

Celcoin は sandbox.openfinance.celcoin.dev にサンドボックスを提供しています。使用するには CELCOIN_SANDBOX=true を設定します。

CELCOIN_SANDBOX を設定しない場合、サーバーは Celcoin の本番環境 api.openfinance.celcoin.com.br を呼び出します（0.2.3 までのデフォルトは、存在しないホスト api-sec.celcoin.com.br でした）。Celcoin への本番呼び出しは、Celcoin が発行する証明書を用いた mTLS 経由で、事前に登録した IP からのみ受け付けられます（Celcoin のドキュメント）。それ以外の IP からのトークン呼び出しには 401 "O seu IP ou certificado digital nao foi reconhecido" が返されます。このサーバーはクライアント証明書を提示しないため、本番環境では CELCOIN_BASE_URL を証明書を保持し mTLS を終端するプロキシに設定してください。本番環境を直接呼び出すと、この 401 が返されます。

認証情報の取得

1. Celcoin Documentation にアクセスします
2. 開発者アカウントを作成します
3. アプリケーションを登録して OAuth2 認証情報を取得します
4. 環境変数を設定します

環境変数

変数	必須	説明
CELCOIN_CLIENT_ID	はい	OAuth2 クライアント ID
CELCOIN_CLIENT_SECRET	はい	OAuth2 クライアントシークレット
CELCOIN_SANDBOX	いいえ	サンドボックスモードを使うには "true" に設定します
CELCOIN_BASE_URL	いいえ	API ホストを上書きします。デフォルト：https://api.openfinance.celcoin.com.br（本番環境）、https://sandbox.openfinance.celcoin.dev（サンドボックス）

ロードマップ

v0.2（予定）

• get_pix_key — Pix キーの詳細を取得します（DICT 照会）
• create_bill_payment — 請求書／公共料金の支払いを作成します
• get_bill_payment — 請求書の支払い詳細を取得します
• create_scheduled_transfer — 予約振込を作成します
• list_providers — 利用可能なサービスプロバイダーを一覧表示します

v0.3（予定）

• batch_topups — 複数のモバイルチャージを処理します
• detailed_reports — 詳細な取引レポートを生成します

コントリビュートをご希望ですか？PR を作成するか、ツールをリクエストしてください。

リンク

• Celcoin のウェブサイト
• Celcoin API ドキュメント
• MCP Dev LATAM
• ランディングページ

エンタープライズ

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

ライセンス

MIT