@codespar/mcp-celcoin

MCP server for Celcoin — BaaS infrastructure for Pix, boleto, transfers, and top-ups

Quick Start

Claude Desktop

Add to ~/.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

Add to .cursor/mcp.json or .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"
      }
    }
  }
}

Tools (18)

| Tool | Purpose | |---|---| | create_pix_payment | Create a Pix payment via Celcoin | | get_pix_payment | Get Pix payment details by transaction ID | | create_pix_cob | Create a Pix immediate charge (cob) — generates QR code / copia-e-cola for payer | | get_pix_cob | Get a Pix immediate charge by transactionId or txid | | create_pix_cobv | Create a Pix due charge (cobv) — boleto-like Pix with due date | | lookup_pix_dict | Lookup a Pix DICT key — resolves a Pix key to account holder + bank info | | create_pix_devolution | Create a Pix devolução (refund) — refund a received Pix transaction | | cancel_boleto | Cancel a boleto issued via the bill-issuance product by id | | read_barcode | Authorize (consult) a boleto / concessionária barcode before paying — returns transactionId, amount, totalUpdated, dueDate | | pay_bill | Confirm payment of a previously authorized bill — pass the read_barcode transactionId as transactionIdAuthorize | | get_statement | Get account statement (extrato) for a date range | | list_topup_providers | List telecom top-up providers (operadoras) available for recargas | | create_boleto | Issue a boleto via the bill-issuance product | | get_boleto | Get an issued boleto's details by id | | create_transfer | Create a bank transfer (TED/DOC) via Celcoin | | get_balance | Get account balance at Celcoin | | list_banks | List available banks in Brazil (ISPB codes) | | create_topup | Create a mobile/service top-up (recarga) via Celcoin |

Authentication

Celcoin uses OAuth2 client credentials. The server automatically manages token refresh.

Sandbox / Testing

Celcoin provides a sandbox at sandbox.openfinance.celcoin.dev. Set CELCOIN_SANDBOX=true to use it.

Without CELCOIN_SANDBOX, the server calls Celcoin production at api.openfinance.celcoin.com.br (up to 0.2.3 the default was api-sec.celcoin.com.br, a host that does not exist). Celcoin accepts production calls only over mTLS, with a certificate Celcoin issues, and only from IPs you registered with them in advance (Celcoin docs). From any other IP the token call answers 401 "O seu IP ou certificado digital nao foi reconhecido". This server does not present a client certificate, so in production point CELCOIN_BASE_URL at a proxy that holds the certificate and terminates the mTLS; called directly, production answers that 401.

Get your credentials

1. Go to Celcoin Documentation
2. Create a developer account
3. Register an application to get OAuth2 credentials
4. Set the environment variables

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | CELCOIN_CLIENT_ID | Yes | OAuth2 client ID | | CELCOIN_CLIENT_SECRET | Yes | OAuth2 client secret | | CELCOIN_SANDBOX | No | Set to "true" for sandbox mode | | CELCOIN_BASE_URL | No | Override the API host. Defaults: https://api.openfinance.celcoin.com.br (production), https://sandbox.openfinance.celcoin.dev (sandbox) |

Roadmap

v0.2 (planned)

• get_pix_key — Get Pix key details (DICT lookup)
• create_bill_payment — Create a bill/utility payment
• get_bill_payment — Get bill payment details
• create_scheduled_transfer — Create a scheduled transfer
• list_providers — List available service providers

v0.3 (planned)

• batch_topups — Process multiple mobile top-ups
• detailed_reports — Generate detailed transaction reports

Want to contribute? Open a PR or request a tool.

Links

• Celcoin Website
• Celcoin API Documentation
• MCP Dev LATAM
• Landing Page

Enterprise

Need governance, budget limits, and audit trails for agent payments? CodeSpar Enterprise adds policy engine, payment routing, and compliance templates on top of these MCP servers.

License

MIT