@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 Brasil
• 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