mcp-celcoin — Claude Code MCP server: Pix, boleto, transfers
An MCP server that hands your agent Celcoin's payment API: Pix charges, boletos, TED/DOC transfers, top-ups. Handy when a Brazilian payment has to happen from the chat.
claude mcp add mcp-celcoin -e CELCOIN_CLIENT_SECRET=<CELCOIN_CLIENT_SECRET> -- npx -y @codespar/mcp-celcoinWhat mcp-celcoin does
Eighteen tools are exposed. The agent can open a Pix payment or an immediate cob charge with a QR code, issue and cancel a boleto, read a bill barcode and then confirm the payment, send a TED/DOC transfer. Lookups come along too: balance, statement for a date range, Brazilian banks by ISPB code, telecom operators for top-ups.
Auth is OAuth2 client credentials and the server refreshes the token on its own. You supply CELCOIN_CLIENT_ID and CELCOIN_CLIENT_SECRET from a Celcoin developer account. Testing runs against sandbox.openfinance.celcoin.dev, switched on with CELCOIN_SANDBOX=true.
Production is the awkward part. Celcoin only accepts live calls over mTLS using a certificate they issue, and only from IPs registered with them beforehand. This server presents no client certificate, so a direct production call answers 401. Point CELCOIN_BASE_URL at a proxy that holds the certificate and terminates mTLS.
What it helps with
- open a Pix payment and hand over the QR code
- issue a boleto, then cancel it
- read a bill barcode before paying
- send a TED/DOC transfer from the agent
- top up a phone through a telecom operator
Example prompts for the agent
- Create a Pix payment for 150 reais and show me the copia-e-cola
- Read the barcode in
boleto.txtand tell me the amount and due date - Pull my Celcoin statement for last week
How to install mcp-celcoin
Platform CLI
claude mcp add mcp-celcoin -e CELCOIN_CLIENT_SECRET=<CELCOIN_CLIENT_SECRET> -- npx -y @codespar/mcp-celcoinReplace <…> with your own values
Platform CLI
codex mcp add celcoin --env CELCOIN_CLIENT_SECRET=<CELCOIN_CLIENT_SECRET> -- npx -y @codespar/mcp-celcoinReplace <…> with your own values
Config file
{
"mcpServers": {
"celcoin": {
"command": "npx",
"args": [
"-y",
"@codespar/mcp-celcoin"
],
"env": {
"CELCOIN_CLIENT_SECRET": "<CELCOIN_CLIENT_SECRET>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"celcoin": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@codespar/mcp-celcoin"
],
"env": {
"CELCOIN_CLIENT_SECRET": "<CELCOIN_CLIENT_SECRET>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e CELCOIN_CLIENT_SECRET=<CELCOIN_CLIENT_SECRET> celcoin npx -y @codespar/mcp-celcoinReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about mcp-celcoin
How do I install mcp-celcoin in Claude Code?
Run claude mcp add mcp-celcoin -e CELCOIN_CLIENT_SECRET=<CELCOIN_CLIENT_SECRET> -- npx -y @codespar/mcp-celcoin, with your own secret in place of the placeholder.
What does mcp-celcoin do?
It exposes Celcoin tools to the agent: Pix, boleto issuance, TED/DOC transfers, bill payment, phone top-ups, balance and statement.
Why does production return 401?
Live calls need mTLS with a Celcoin-issued certificate and a pre-registered IP. The server sends no certificate, so route requests through a proxy that terminates mTLS and set its address in CELCOIN_BASE_URL.
