Skip to main content
Glama
Asaas MCP Server

Asaas MCP Server

by macedoflp

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 (offset e limit) 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 o walletId da 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

ASAAS_API_KEY

Sim (para chamadas)

—

Chave de API gerada no painel do Asaas (Produção ou Sandbox).

ASAAS_ENVIRONMENT

Não

production

Defina como sandbox para usar o ambiente de testes (https://sandbox.asaas.com/api/v3).

ASAAS_BASE_URL

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_KEY configurada 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 ferramenta get_wallet_id). Não envie o walletId da 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 tools
cancel_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

    B3.3/5.0

    Scored across 16 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness3/5

    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

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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 npm
      7
      MIT
    • F
      license
      B
      quality
      Not graded
      maintenance
      Enables 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
      -
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables 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.
      -