mcp-asaas

@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"
      }
    }
  }
}

Tools (24)

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

1. Go to Asaas
2. Create an account or sign up for sandbox at sandbox.asaas.com
3. Navigate to Integracoes > API and generate your API key
4. 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.

# Start the server in demo mode (no key required):
npx -y @codespar/mcp-asaas --demo

Roadmap

v0.2 (planned)

• list_subscriptions — List all recurring subscriptions with filters
• cancel_subscription — Cancel an active subscription
• get_webhook_events — List webhook events for debugging integrations
• create_subaccount — Create a subaccount for marketplace splits
• get_installments — Get installment details for a payment

v0.3 (planned)

• create_anticipation — Request anticipation of receivables
• get_fiscal_info — Get fiscal/tax information for payments
• batch_payments — Create multiple payments in a single request

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

Links

• Asaas Website
• Asaas 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