mcp-cielo — Claude Code MCP server: what it does, how to install
Wires Cielo payments into your coding agent: card sales, boleto, Pix, recurring charges and payment links, as 22 callable tools. Handy when billing logic lives in the repo you are editing.
claude mcp add mcp-cielo -e CIELO_API_KEY=<CIELO_API_KEY> -- npx -y @codespar/mcp-cieloWhat mcp-cielo does
The server talks to the Cielo acquiring API on the agent's behalf. You can open a card sale, capture one that was only pre-authorized, and void it in full or in part. Boleto and Pix are covered too, the latter with a QR code. Recurring credit card plans are managed from the same place: change the amount, move the next charge date, pause the plan, bring it back.
Stored card tokens let you charge a customer again without asking for the card number, and a zero-dollar authorization checks a card without moving money. Authentication uses MerchantId and MerchantKey headers, so you need both credentials from the Cielo developer portal. Testing runs against the Cielo sandbox once CIELO_SANDBOX=true is set; the host switches to apisandbox.cieloecommerce.cielo.com.br.
One thing to watch: the tool table lists Pix, debit, wallets and anti-fraud, while the roadmap in the same repository still marks several of those as planned for version 0.2. Check which tools actually load before you build a flow around them. Debit sales additionally require 3DS authentication.
What it helps with
- charge a credit or debit card through Cielo
- issue a boleto for an order
- generate a Pix payment with a QR code
- set up a recurring charge and adjust its amount
- validate a card with a zero-dollar authorization
Example prompts for the agent
- Pull the details for sale PaymentId 123456789
- Create a recurring payment for 49.90 and pause it before the next charge
- Generate a payment link for order 8842
How to install mcp-cielo
Platform CLI
claude mcp add mcp-cielo -e CIELO_API_KEY=<CIELO_API_KEY> -- npx -y @codespar/mcp-cieloReplace <…> with your own values
Platform CLI
codex mcp add cielo --env CIELO_API_KEY=<CIELO_API_KEY> -- npx -y @codespar/mcp-cieloReplace <…> with your own values
Config file
{
"mcpServers": {
"cielo": {
"command": "npx",
"args": [
"-y",
"@codespar/mcp-cielo"
],
"env": {
"CIELO_API_KEY": "<CIELO_API_KEY>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"cielo": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@codespar/mcp-cielo"
],
"env": {
"CIELO_API_KEY": "<CIELO_API_KEY>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e CIELO_API_KEY=<CIELO_API_KEY> cielo npx -y @codespar/mcp-cieloReplace <…> 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-cielo
How do I install mcp-cielo in Claude Code?
Run claude mcp add mcp-cielo -e CIELO_API_KEY=<CIELO_API_KEY> -- npx -y @codespar/mcp-cielo. Fill in your Cielo MerchantId and MerchantKey through the environment variables.
What does mcp-cielo do?
It exposes the Cielo payment gateway to the agent: card sales, boleto, Pix, recurring payments, card tokenization, payment links and anti-fraud lookups.
Can I test without real money?
Yes. With CIELO_SANDBOX=true the server points at the Cielo sandbox at apisandbox.cieloecommerce.cielo.com.br.
