About mcp-cielo
mcp-cielo is an MCP server for Cielo, a Brazilian card acquiring provider. It offers 22 tools for card sales, Pix, boleto, recurring payments and payment links. It is aimed at merchants and developers handling online payments in Brazil.
Key features
- 0122 MCP tools for cards, Pix and boleto
- 02Creation, amount and date updates for recurring payments
- 03Support for CardToken and 3DS 2.0 authentication data
- 04Anti-fraud analysis and payment link lookup
Use cases
- 01Creating, capturing or cancelling sales through an agent
- 02Managing recurring payment amounts, next dates and status
- 03Generating Pix QR codes or Cielo payment links
MCP support
This project is an MCP server that exposes Cielo payment, recurring payment, Pix, boleto, anti-fraud and payment link operations as tools for MCP clients.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
Tools
22Saved tool list · updated 2w ago
| Parameter | Type | Required | Description |
|---|---|---|---|
| brand | enum | Yes | Card brandVisa | Master | Elo | Amex | Hipercard |
| amount | number | Yes | Amount in cents (e.g., 15700 = R$157.00) |
| holder | string | Yes | Cardholder name |
| capture | boolean | No | Auto-capture (true for immediate capture) |
| cardNumber | string | Yes | Credit card number |
| customerName | string | Yes | Customer name |
| installments | number | No | Number of installments (1 for full payment) |
| securityCode | string | Yes | CVV |
| expirationDate | string | Yes | Expiration date (MM/YYYY) |
| merchantOrderId | string | Yes | Merchant order reference |
Details
From the project README@codespar/mcp-cielo
MCP server for Cielo — card acquiring, boleto, and recurrent payments
Quick Start
Claude Desktop
Add to ~/.config/claude/claude_desktop_config.json:
{
"mcpServers": {
"cielo": {
"command": "npx",
"args": ["-y", "@codespar/mcp-cielo"],
"env": {
"CIELO_MERCHANT_ID": "your-merchant-id",
"CIELO_MERCHANT_KEY": "your-merchant-key",
"CIELO_SANDBOX": "true"
}
}
}
}
Claude Code
claude mcp add cielo -- npx @codespar/mcp-cielo
Cursor / VS Code
Add to .cursor/mcp.json or .vscode/mcp.json:
{
"servers": {
"cielo": {
"command": "npx",
"args": ["-y", "@codespar/mcp-cielo"],
"env": {
"CIELO_MERCHANT_ID": "your-merchant-id",
"CIELO_MERCHANT_KEY": "your-merchant-key",
"CIELO_SANDBOX": "true"
}
}
}
}
Tools (22)
| Tool | Purpose |
|---|---|
create_sale | Create a credit/debit card sale in Cielo |
get_sale | Get sale details by PaymentId |
capture_sale | Capture a pre-authorized sale |
cancel_sale | Cancel/void a sale (full or partial) |
create_recurrent | Create a recurrent (recurring) credit card payment |
get_recurrent | Get recurrent payment details |
tokenize_card | Tokenize a credit card for future use |
create_boleto | Create a boleto payment in Cielo |
create_pix | Create a Pix payment in Cielo (generates QR code) |
get_pix | Get Pix payment details and QR code by PaymentId |
create_debit | Create a debit card sale in Cielo (requires 3DS authentication) |
create_ewallet | Create a digital wallet payment (Google Pay, Samsung Pay, Apple Pay) |
get_antifraud | Get anti-fraud analysis details for a payment |
create_sale_with_token | Create a credit card sale using a previously stored CardToken (avoids re-entering card data) |
update_recurrent_amount | Update the amount of an existing recurrent payment |
update_recurrent_next_date | Update the next charge date of an existing recurrent payment |
deactivate_recurrent | Deactivate (pause) a recurrent payment so it stops charging |
reactivate_recurrent | Reactivate a previously deactivated recurrent payment |
create_payment_link | Create a Cielo Link de Pagamento (shareable checkout URL) |
get_payment_link | Get a Cielo Link de Pagamento by its id |
zero_auth | Zero-dollar authorization to validate a card without charging (card or CardToken) |
create_sale_with_3ds | Create a credit card sale using 3DS 2.0 authentication data (from 3DS flow) |
Authentication
Cielo uses MerchantId and MerchantKey headers for authentication.
Sandbox / Testing
Cielo provides a sandbox at apisandbox.cieloecommerce.cielo.com.br. Set CIELO_SANDBOX=true to use it.
Get your credentials
- Go to Cielo Developer Portal
- Create a developer account
- Get your MerchantId and MerchantKey
- Set the environment variables
Environment Variables
| Variable | Required | Description |
|---|---|---|
CIELO_MERCHANT_ID | Yes | Merchant ID from Cielo |
CIELO_MERCHANT_KEY | Yes | Merchant Key from Cielo |
CIELO_SANDBOX | No | Set to "true" for sandbox mode |
Roadmap
v0.2 (planned)
create_pix— Create a Pix paymentget_pix— Get Pix payment detailscreate_debit— Create a debit card paymentcreate_ewallet— Create an e-wallet payment (Apple Pay, Google Pay)get_antifraud— Get anti-fraud analysis for a transaction
v0.3 (planned)
batch_captures— Capture multiple pre-authorized transactionsvelocity_rules— Configure velocity/anti-fraud rules
Want to contribute? Open a PR or request a tool.
Links
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
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.