@codespar/mcp-asaas
MCP server for Asaas — billing automation with Pix, boleto, and credit card payments
Quick Start
Claude Desktop
Add to ~/.config/claude/claude_desktop_config.json:
{
"mcpServers": {
"asaas": {
"command": "npx",
"args": ["-y", "@codespar/mcp-asaas"],
"env": {
"ASAAS_API_KEY": "your-key",
"ASAAS_SANDBOX": "true"
}
}
}
}
Claude Code
claude mcp add asaas -- npx @codespar/mcp-asaas
Cursor / VS Code
Add to .cursor/mcp.json or .vscode/mcp.json:
{
"servers": {
"asaas": {
"command": "npx",
"args": ["-y", "@codespar/mcp-asaas"],
"env": {
"ASAAS_API_KEY": "your-key",
"ASAAS_SANDBOX": "true"
}
}
}
}
| Tool | Purpose |
|---|
create_payment | Create a payment in Asaas (Pix, boleto, or credit card); pass installments (>=2) with billingType: CREDIT_CARD to split into equal monthly installments |
get_payment | Get payment details by ID |
list_payments | List payments with optional filters |
get_pix_qrcode | Get Pix QR code for a payment (returns payload and image) |
get_boleto | Get boleto digitable line and barcode for a payment |
create_customer | Create a customer in Asaas |
list_customers | List customers with optional filters |
create_subscription | Create a recurring subscription |
get_balance | Get current account balance |
list_subscriptions | List subscriptions with optional filters |
cancel_subscription | Cancel a subscription by ID |
get_webhook_events | List webhook events (payment confirmations, transfers, etc.) |
create_subaccount | Create a subaccount for payment splitting |
get_installments | Get installment details for an existing payment by id, OR preview a hypothetical schedule by passing value + installments without an id |
create_transfer | Create a bank transfer (Pix out or TED) |
create_pix_qrcode | Generate a static PIX QR code for receiving payments |
list_transfers | List transfers with optional filters |
create_notification | Create a webhook notification configuration |
list_notifications | List webhook notification configurations |
get_customer | Get customer details by ID |
update_payment | Update a pending payment |
delete_payment | Delete a payment by ID |
refund_payment | Refund a received payment |
get_subscription | Get subscription details by ID |
Authentication
Asaas uses an API key passed via the access_token header. You can generate your key from the Asaas dashboard.
Sandbox / Testing
Asaas provides a full sandbox environment at sandbox.asaas.com. Set ASAAS_SANDBOX=true to use it.
Get your credentials
- Go to Asaas
- Create an account or sign up for sandbox at sandbox.asaas.com
- Navigate to Integracoes > API and generate your API key
- Set the
ASAAS_API_KEY environment variable
Environment Variables
| Variable | Required | Description |
|---|
ASAAS_API_KEY | Yes (unless in demo mode) | API key from Asaas dashboard |
ASAAS_SANDBOX | No | Set to "true" for sandbox mode |
MCP_DEMO | No | Set to "true" (equivalent to passing --demo on the command line) for stateful demo-mode fixtures — no API key required |
Demo mode
Pass the --demo flag (or set MCP_DEMO=true) to make every tool
return deterministic fixture responses instead of calling the real
Asaas API. Useful for building and testing agents without burning
sandbox credentials.
The demo handlers for create_payment and get_installments are
stateful: create_payment issues distinct ids per call
(pay_demo_001, pay_demo_002, ...) and, when called with
billingType: CREDIT_CARD + installments >= 2 + value > 0,
records the installment schedule in an in-process ledger. A
subsequent get_installments({ id }) against that id echoes the
recorded schedule back. get_installments also supports a preview
path — pass value + installments without an id and it returns
a hypothetical schedule (status: "PREVIEW", preview: true)
without creating a payment. Other tools return static fixture
payloads.
npx -y @codespar/mcp-asaas --demo
Roadmap
v0.2 (planned)
list_subscriptions — List all recurring subscriptions with filterscancel_subscription — Cancel an active subscriptionget_webhook_events — List webhook events for debugging integrationscreate_subaccount — Create a subaccount for marketplace splitsget_installments — Get installment details for a payment
v0.3 (planned)
create_anticipation — Request anticipation of receivablesget_fiscal_info — Get fiscal/tax information for paymentsbatch_payments — Create multiple payments in a single request
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