Asaas MCP Server
Provides tools for creating and managing Pix charges, generating dynamic QR codes and Copia e Cola keys, checking Pix payment status, and handling refunds through the Asaas payment gateway.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Asaas MCP Server Crie uma cobrança Pix de R$ 150 para o cliente cus_000005931980"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Asaas MCP Server 🚀
Servidor Model Context Protocol (MCP) para integração completa com a API v3 do Asaas (gateway brasileiro de pagamentos e Pix).
Permite que assistentes de IA (como Google Antigravity, Claude Desktop, Cursor, etc.) consultem, criem e gerenciem cobranças Pix, Boletos, Cartão de Crédito, Assinaturas, Subcontas, Webhooks e Split de Pagamentos.
🛠️ Ferramentas Disponíveis (15 Tools)
💳 1. Cobranças & Pix
create_payment: Cria uma cobrança (Pix, Boleto, Cartão de Crédito) com suporte completo a Split de Pagamentos e parcelamento.get_payment: Consulta dados e status atualizado de qualquer cobrança (PENDING,RECEIVED,CONFIRMED,OVERDUE, etc.).list_payments: Lista cobranças com paginação oficial (offsetelimit) e filtros por status, cliente, data e identificadores.create_pix_qr: Gera o QR Code dinâmico em base64 e a chave Copia e Cola Pix da cobrança.get_pix_status: Consulta direta do status e conciliação de uma cobrança Pix.refund_payment: Realiza estorno total ou parcial de pagamentos.simulate_payment: Simula o recebimento de uma cobrança (ideal para testes no ambiente Sandbox).
👥 2. Clientes
create_customer: Cadastra clientes com dados completos (CPF/CNPJ, e-mail, telefone para WhatsApp/SMS, endereço).list_customers: Pesquisa e lista clientes cadastrados com paginação (offset/limit) e filtros.
🔁 3. Assinaturas & Recorrência
create_subscription: Cria planos ou mensalidades recorrentes (WEEKLY,MONTHLY,YEARLY, etc.) com suporte a Split por mensalidade.list_subscriptions: Lista assinaturas ativas, inativas e expiradas.cancel_subscription: Cancela uma assinatura recorrente no Asaas.
🔀 4. Split de Pagamentos, Subcontas & Conta
get_wallet_id: Retorna owalletIdda conta autenticada (necessário para receber repasses em Splits).get_account_status: Consulta a situação cadastral, bancária e de aprovação da conta.create_subaccount: Cria subcontas filhas no Asaas para onboarding de parceiros em marketplaces.configure_webhook: Configura endpoints de webhook para receber notificações (PAYMENT_RECEIVED,PAYMENT_SPLIT_DONE, etc.).
Related MCP server: Vaultix MCP Server
⚙️ Variáveis de Ambiente
Variável | Obrigatória | Padrão | Descrição |
| Sim (para chamadas) | — | Chave de API gerada no painel do Asaas (Produção ou Sandbox). |
| Não |
| Defina como |
| Não | — | Sobrescreve a URL base da API (ex: proxies ou mocks internos). |
Nota: O servidor MCP inicializa com sucesso mesmo sem a
ASAAS_API_KEYconfigurada no boot. A validação é feita sob demanda (lazy), retornando uma mensagem clara quando uma ferramenta for executada sem a chave.
🔀 Como Utilizar o Split de Pagamentos
O Split permite distribuir automaticamente o valor de uma venda entre carteiras do Asaas:
{
"customer": "cus_000005931980",
"billingType": "PIX",
"value": 200.00,
"dueDate": "2026-10-31",
"description": "Serviço com repasse de comissão",
"split": [
{
"walletId": "3b7c89a1-1234-5678-90ab-cdef12345678",
"percentualValue": 15.0,
"description": "Comissão do afiliado (15%)"
},
{
"walletId": "7f8e12c3-1234-5678-90ab-cdef12345678",
"fixedValue": 25.00,
"description": "Taxa fixa do parceiro"
}
]
}walletId: ID da carteira de destino (obtido via ferramentaget_wallet_id). Não envie owalletIdda própria conta emissora.percentualValue: Percentual calculado sobre o valor líquido (netValue) após descontadas as taxas do Asaas.totalFixedValue: Para cobranças parceladas, divide o valor fixo total igualmente entre todas as parcelas.
🚀 Como Configurar no Google Antigravity
Adicione o servidor nas configurações de MCP do Antigravity (ex: antigravity.json ou painel de configurações de MCP):
{
"mcpServers": {
"asaas": {
"command": "node",
"args": ["d:/Downloads/asaas-mcp-main/asaas-mcp-main/dist/index.js"],
"env": {
"ASAAS_ENVIRONMENT": "sandbox",
"ASAAS_API_KEY": "${env:ASAAS_API_KEY}"
}
}
}
}Ou usando npx tsx diretamente no código-fonte para desenvolvimento:
{
"mcpServers": {
"asaas": {
"command": "npx",
"args": ["-y", "tsx", "d:/Downloads/asaas-mcp-main/asaas-mcp-main/src/index.ts"],
"env": {
"ASAAS_ENVIRONMENT": "sandbox"
}
}
}
}🧪 Testes & Build
# Executar suíte de testes unitários com Vitest
npm test
# Compilar código TypeScript para dist/
npm run build📄 Licença
MIT
Available Tools
16 toolscancel_subscriptionC
Cancela uma assinatura recorrente no Asaas
Inputs: subscription_id (required).
configure_webhookC
Configura ou atualiza um endpoint de Webhook para receber notificações de pagamentos e splits
Inputs: url (required), name (required), email (required), events, +5 more.
create_customerB
Cadastra um novo cliente no Asaas com dados completos (CPF/CNPJ, e-mail, telefone e endereço)
Inputs: name (required), cpfCnpj (required), email, phone, +8 more.
create_paymentC
Cria uma cobrança (Pix, Boleto, Cartão de Crédito) com suporte a Split de Pagamentos e parcelamento
Inputs: value (required), dueDate (required), customer (required), billingType (required), +6 more.
create_pix_qrC
Gera o QR Code dinâmico e o código Copia e Cola Pix para uma cobrança
Inputs: payment_id (required).
create_subaccountB
Cria uma subconta filha no Asaas (ideal para marketplaces e divisão de splits com parceiros)
Inputs: name (required), email (required), address (required), cpfCnpj (required), +8 more.
create_subscriptionC
Cria uma assinatura/mensalidade recorrente (com suporte a Split recorrente)
Inputs: value (required), customer (required), billingType (required), nextDueDate (required), +5 more.
get_account_statusB
Consulta o status cadastral e situação de aprovação da conta no Asaas
Inputs: no named parameters.
get_paymentC
Consulta os detalhes e o status atualizado de uma cobrança pelo ID
Inputs: payment_id (required).
get_pix_statusB
Verifica o status de pagamento de uma cobrança Pix
Inputs: payment_id (required).
get_wallet_idA
Obtém o walletId da conta Asaas autenticada (necessário para configurar repasses de Split)
Inputs: no named parameters.
list_customersB
Lista e pesquisa clientes cadastrados com paginação (offset/limit)
Inputs: name, email, limit, offset, +2 more.
list_paymentsB
Lista cobranças com paginação oficial (offset/limit) e filtros por status, cliente e vencimento
Inputs: limit, offset, status, customer, +4 more.
list_subscriptionsC
Lista as assinaturas ativas e inativas com filtros e paginação
Inputs: limit, offset, status, customer, +1 more.
refund_paymentC
Realiza o estorno total ou parcial de uma cobrança recebida
Inputs: payment_id (required), value, description.
simulate_paymentA
Simula a confirmação de recebimento de uma cobrança (útil para testes em Sandbox)
Inputs: payment_id (required), value, paymentDate.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
Most tools target distinct resources and actions, but get_pix_status and get_payment overlap in checking payment status, and create_pix_qr could be confused with create_payment for Pix charges. Descriptions help clarify, but minor ambiguity remains.
All tools follow a consistent snake_case verb_noun pattern (e.g., create_customer, list_payments, get_pix_status, cancel_subscription). No mixed conventions or vague naming.
16 tools is slightly above the ideal 3-15 range, but reasonable for a payment platform covering customers, payments, subscriptions, subaccounts, and webhooks. Each tool earns its place, though some consolidation could be possible.
Core create/read operations exist for payments and customers, but notable gaps include no update or delete for customers, no get/update for subscriptions, no list/get/update for subaccounts, and no list/delete for webhooks. These omissions could hinder full lifecycle management.
Related MCP Connectors
Digital account and billing on Asaas with the full official REST API v3 (api.asaas.com), balance, ch
Create Pix charges, check and refund payments, and manage Pix subscriptions in PagSafe.
Manage GoCardless payments, mandates, subscriptions, refunds and payouts via AI assistants.
Issue Brazilian service invoices (NFS-e Nacional) from your AI, with preview and confirmation.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables integration with Abacate Pay API for managing payments, customers, and billing through AI assistants. Supports multi-tenancy, PIX QR codes, discount coupons, and payment simulation with secure per-request API key authentication.26 npm7MIT
- FlicenseBqualityNot gradedmaintenanceEnables Claude to interact with the Vaultix Payment API for managing charges, customers, refunds, payment links, payouts, and balance transactions. Supports Brazilian payment methods including PIX, card, and boleto payments.32-
- AlicenseNot gradedqualityNot gradedmaintenanceEnables AI assistants to interact with Conta Azul Financial APIs to manage accounts, balances, and transactions through natural language. It features specialized tools for tracking cash flow, processing payables and receivables, and generating comprehensive financial reports.-
- AlicenseAqualityDmaintenanceEnables AI assistants to interact with Brazilian electronic invoices (NF-e, NFC-e, NFS-e) via Nuvem Fiscal API, including CNPJ lookup, invoice issuance, cancellation, and PDF generation.161MIT