Skip to main content
Glama
zuckpay-mcp

zuckpay-mcp

Official
by ZuckPay

Servidor MCP oficial da ZuckPay — crie cobranças PIX, SPEI (México) e PayPal, acompanhe vendas no cartão (Stripe e cartão nacional), consulte transações e saldo, e gerencie sua conta (produtos, cursos, assinaturas, infrações, indique&ganhe e mais) direto do seu assistente de IA (Claude Code, Claude Desktop, Cursor e qualquer cliente MCP).

  • Node puro — funciona com npx/node, sem Bun nem build extra.

  • Seguro por padrão — credenciais só via variáveis de ambiente, máscara de segredos em toda saída, saque desabilitado por padrão, dados de cartão jamais trafegam pela IA.

  • 2 dependências de runtime — @modelcontextprotocol/sdk e zod.

Tools

Pagamentos

Tool

O que faz

createPixCharge

Cria cobrança PIX (copia-e-cola + QR Code + checkout hospedado). Suporta idempotência, split, webhook e UTMs

getTransactionStatus

Consulta status por transactionId ou pelo seu external_id_client (PIX, SPEI e cartão)

createSpeiCashin

Cria cobrança SPEI em MXN e retorna a CLABE de 18 dígitos (México)

createPayPalOrder

Cria ordem PayPal em 25 moedas e retorna o link de aprovação

capturePayPalOrder

Captura a ordem depois que o pagador aprova

getCardGateways

Mostra os gateways de cartão da conta — Stripe (internacional) e cartão nacional (BRL) — com as chaves públicas

listTransactions

Lista as transações da conta com filtros (status, tipo, método, período) e paginação por cursor

getBalance

Saldos da conta (disponível, bloqueado em liberação, total) e limites de saque

createPixWithdraw

⚠️ Saque PIX — só existe com ZUCKPAY_ENABLE_WITHDRAW=true (veja Segurança)

Sua conta (somente leitura)

Tudo escopado à conta autenticada — uma chave de seller nunca enxerga dado de outro seller, e dados de comprador (nome, e-mail, CPF, telefone) chegam sempre mascarados (jo***@gmail.com, 123.***.***-**).

Tool

O que faz

getSalesToday

Resumo das vendas de hoje: total pago, quantidade, ticket médio, breakdown por método e pendentes

listProducts

Lista seus produtos (nome, preço, status, moeda, métodos de pagamento habilitados)

getProduct

Detalha um produto pelo id

listCourses

Lista seus cursos (área de membros): módulos, aulas e nº de alunos matriculados

listSubscriptions

Assinaturas da conta: produto, status (ativa/cancelada/inativa/pendente), valor, periodicidade

listInfractions

Chargebacks e pedidos de reembolso (Infrações e MED), com status e prazos

getReferralStats

Seu Indique & Ganhe: total de indicados, comissões pendentes/liberadas e histórico

getStore

Sua loja (vitrine): nome, slug, template, status de publicação e domínio

listAcquirerRoutes

Rotas de adquirente disponíveis pra sua conta, com taxa de conversão — as mesmas do painel

listPaymentLinks

Seus links de pagamento (valor, método, views, status)

listIntegrationKeys

Metadados das suas chaves de API (nome, domínio, criação) — nunca o client_secret

listWebhooks

Webhooks configurados na conta (URL, eventos, produtos, status)

Criar/editar/apagar qualquer coisa por aqui não existe ainda — escrita é a próxima fase, sempre atrás de confirmação explícita. Ações sensíveis (revelar/rotacionar chave, excluir produto, publicar loja) ficam só no painel, por design.

Extras: resource zuckpay://docs/api (referência da API + validação do webhook assinado) e prompt criar-cobranca-pix.

Related MCP server: @formacv/mcp

Instalação

Gere suas credenciais no painel ZuckPay em Desenvolvedores → Credenciais API.

Claude Code

claude mcp add zuckpay \
  -e ZUCKPAY_CLIENT_ID=seu_client_id \
  -e ZUCKPAY_CLIENT_SECRET=seu_client_secret \
  -- npx -y zuckpay-mcp

Claude Desktop / Cursor

claude_desktop_config.json (ou .cursor/mcp.json):

{
  "mcpServers": {
    "zuckpay": {
      "command": "npx",
      "args": ["-y", "zuckpay-mcp"],
      "env": {
        "ZUCKPAY_CLIENT_ID": "seu_client_id",
        "ZUCKPAY_CLIENT_SECRET": "seu_client_secret"
      }
    }
  }
}

Variáveis de ambiente

Variável

Obrigatória

Descrição

ZUCKPAY_CLIENT_ID

✅

Client ID da integração

ZUCKPAY_CLIENT_SECRET

✅

Client Secret da integração

ZUCKPAY_ENABLE_WITHDRAW

—

true habilita a tool de saque (padrão: desabilitada)

ZUCKPAY_BASE_URL

—

Override da base da API (somente https://; padrão https://www.zuckpay.com.br/conta)

Exemplos de uso

"Cria uma cobrança PIX de R$ 97,00 pro cliente João Silva, CPF 123.456.789-01, joao@email.com, (11) 99999-8888, com ID externo PEDIDO-4512"

"Qual o status da transação do pedido PEDIDO-4512?"

"Cria uma ordem PayPal de US$ 50 pro comprador Mike Ross, mike@email.com"

"Lista minhas vendas de cartão pagas neste mês e diz quanto ainda está em liberação"

"Quanto eu vendi hoje? Divide por método de pagamento"

"Tenho algum chargeback ou pedido de reembolso aberto?"

"Como tá meu Indique & Ganhe? Quanto tenho de comissão pra liberar?"

"Lista minhas assinaturas ativas e me diz qual produto tem mais assinantes"

Cartão: como o MCP se encaixa

O MCP acompanha as vendas de cartão, mas não cria cobrança de cartão — e isso é proposital (veja Segurança):

O que você quer fazer

Como fazer

Cobrar no cartão

Checkout hospedado ou link de pagamento da ZuckPay — o dado do cartão nunca passa pela IA

Ver os gateways de cartão da conta

getCardGateways — Stripe (internacional) e cartão nacional (BRL), com as chaves públicas de tokenização

Conferir se uma venda de cartão foi paga

getTransactionStatus com o transactionId ou o seu external_id_client

Listar as vendas de cartão de um período

listTransactions com payment_method: credit_card

Ver quanto de cartão ainda está em liberação

getBalance — o saldo bloqueado inclui vendas de cartão aguardando o prazo da conta (ex.: D+8); PIX libera em D+0

Por que o MCP não cobra cartão? PCI DSS: número e CVV jamais devem trafegar pelo contexto de um LLM. A tokenização acontece no navegador do pagador, dentro do checkout hospedado — e o MCP entra depois, para consultar status, listar vendas e conferir o saldo.

Segurança

  • Credenciais: aceitas SOMENTE via variáveis de ambiente — nunca por argumento de linha de comando (vazaria na lista de processos) nem por parâmetro de tool. A autenticação vai apenas no header Authorization: Basic, jamais no corpo JSON.

  • Máscara de segredos: toda string que sai do processo (resultado de tool, erro, log em stderr) passa por um redactor que mascara o client_id, o client_secret e a forma base64 de ambos.

  • Saque é opt-in duplo: a tool createPixWithdraw nem sequer é registrada sem ZUCKPAY_ENABLE_WITHDRAW=true; com ela, o schema ainda exige confirm: true e instrui o modelo a confirmar valor, chave e tipo com o usuário humano antes de chamar. Limites: R$ 50,00 a R$ 20.000,00 por saque, e o gateway valida o saldo disponível do vendedor antes de executar.

  • Cartão: a cobrança direta de cartão não existe neste MCP por design — PAN/CVV nunca devem passar pelo contexto de um LLM (PCI DSS). Só as chaves públicas são expostas; a cobrança acontece no checkout hospedado.

  • Sem retry em dinheiro: requisições POST nunca são repetidas automaticamente; somente GET /pix/status retenta uma única vez, e apenas em falha de rede.

  • PII do comprador em barreira dupla: o servidor já devolve nome/e-mail/CPF/telefone mascarados; ainda assim, as tools de conta varrem cada resposta atrás de PII crua (assertNoRawPii) e falham em vez de vazar se o backend algum dia regredir. Campos como refund_token são bloqueados por nome.

  • Validação estrita: toda entrada passa por schemas zod .strict() (campos desconhecidos são rejeitados) antes de qualquer chamada; o corpo enviado à API é montado campo a campo (allowlist).

  • Encontrou uma vulnerabilidade? Veja SECURITY.md.

Webhook assinado (recomendado)

Ao informar urlnoty, seu endpoint recebe o postback de confirmação. Contas com webhook secret recebem os headers:

X-ZuckPay-Timestamp: <unix_ts>
X-ZuckPay-Signature: t=<unix_ts>,v1=<hex>

onde v1 = HMAC-SHA256("<unix_ts>.<body_cru>", secret). Valide sempre sobre o body cru e rejeite timestamps velhos (ex.: > 5 min). Exemplo completo em Node.js e PHP no resource zuckpay://docs/api.

Modo HTTP hospedado (multi-tenant)

Além do stdio, o servidor tem um modo Streamable HTTP stateless pensado para hospedagem (ex.: mcp.zuckpay.com.br): cada seller conecta o próprio cliente MCP na URL e autentica com a própria credencial, sem instalar nada.

npm run build && npm run start:http   # POST /mcp + GET /healthz na porta $PORT (padrão 8080)
  • Autenticação por request: Authorization: Basic base64(client_id:client_secret). Nada de credencial em URL/query, e nenhuma credencial é logada.

  • Stateless de verdade: nenhum estado entre requests → escala horizontal sem sticky session.

  • Endurecimento embutido: rate limit por IP (429 + Retry-After), body máx. 256 KB, timeouts anti-slowloris, X-Content-Type-Options: nosniff, sem CORS.

  • A tool de saque não é exposta no modo hospedado, a menos que o operador do serviço suba com ZUCKPAY_ENABLE_WITHDRAW=true (não recomendado em multi-tenant).

Cliente (ex.: Claude Code):

claude mcp add --transport http zuckpay https://mcp.zuckpay.com.br/mcp \
  --header "Authorization: Basic $(printf 'seu_client_id:seu_client_secret' | base64)"

Variáveis do serviço HTTP: PORT (padrão 8080), MCP_TRUST_PROXY=true (atrás de proxy/Railway), MCP_RATE_LIMIT_PER_MINUTE (padrão 60).

Deploy com Docker: docker build -t zuckpay-mcp . && docker run -p 8080:8080 zuckpay-mcp — imagem alpine com usuário non-root e HEALTHCHECK. Para Railway, o railway.toml já aponta o Dockerfile e o healthcheck.

Desenvolvimento

npm ci
npm run lint && npm run typecheck && npm test
npm run build          # gera dist/index.js (stdio) e dist/http.js (HTTP)
npm run inspector      # debug com o MCP Inspector

Licença

MIT

Available Tools

20 tools
capturePayPalOrderCapturar ordem PayPalA
Idempotent

Captura (efetiva) uma ordem PayPal já aprovada pelo pagador. Chame somente depois que o pagador abriu o link de aprovação e concluiu o fluxo no PayPal. A captura é idempotente do lado do PayPal.

Inputs: orderId (required).

createPayPalOrderCriar ordem PayPalA

Cria uma ordem de pagamento no PayPal via ZuckPay e retorna o link de aprovação para o pagador. Suporta 25 moedas (padrão: BRL). Após o pagador aprovar, use capturePayPalOrder para efetivar.

Inputs: nome (required), email (required), valor (required), urlnoty, +5 more.

createPixChargeCriar cobrança PIXB

Cria uma cobrança PIX na ZuckPay e retorna o código copia-e-cola, a imagem do QR Code e o link de checkout hospedado. Suporta idempotência (external_id_client), split de receita entre contas, webhook de confirmação (urlnoty) e parâmetros de rastreio (UTMs). Valor em reais com até 2 casas decimais.

Inputs: cpf (required), nome (required), email (required), valor (required), +22 more.

createSpeiCashinCriar cobrança SPEI (México)A

Cria uma cobrança SPEI em pesos mexicanos (MXN) e retorna a CLABE de 18 dígitos para o pagador transferir de qualquer banco do México. Requer conta ZuckPay com SPEI habilitado. Documento do pagador: RFC ou CURP.

Inputs: nome (required), email (required), valor (required), documento (required).

getBalanceConsultar saldo da contaA
Read-only

Consulta os saldos da conta ZuckPay autenticada: disponível para saque, bloqueado (em liberação — PIX libera em D+0; cartão segue o prazo da conta, ex.: D+8) e total, além dos limites e taxa de saque vigentes. Somente leitura, sem parâmetros.

Inputs: no named parameters.

getCardGatewaysListar gateways de cartão (chaves públicas)A
Read-only

Lista os gateways de cartão disponíveis na conta ZuckPay (Stripe internacional e/ou cartão nacional BRL) com suas chaves públicas (publishable keys). Somente leitura — a cobrança direta de cartão não é exposta via MCP por segurança (PCI); use o checkout hospedado da ZuckPay.

Inputs: no named parameters.

getProductDetalhar produtoA
Read-only

Retorna os detalhes de um produto específico da conta ZuckPay autenticada, pelo ID. Somente leitura.

Inputs: id (required).

getReferralStatsIndique e GanheA
Read-only

Estatísticas do programa Indique&Ganhe do seller autenticado: total de indicados, comissões (total/pendente/liberada), lista de indicados e histórico de comissões. Somente leitura, escopado estritamente ao próprio seller — nunca retorna ranking ou dado de outros sellers.

Inputs: no named parameters.

getSalesTodayVendas de hojeA
Read-only

Resumo agregado das vendas do dia (horário de Brasília) da conta ZuckPay autenticada: total pago, contagem, ticket médio, breakdown por método de pagamento e total pendente. Somente leitura, não retorna transações individuais nem dado de comprador.

Inputs: no named parameters.

getStoreDetalhar lojaA
Read-only

Retorna os dados da loja (storefront) da conta ZuckPay autenticada: nome, status, slug, domínio, descrição e redes sociais. Somente leitura — não retorna código customizado nem config de pagamento.

Inputs: no named parameters.

getTransactionStatusConsultar status de transaçãoA
Read-only

Consulta o status de uma transação ZuckPay (PIX, SPEI ou cartão) pelo transactionId OU pelo external_id_client do seu sistema (exatamente um dos dois). Status possíveis: PENDING, PAID, FAILED, EXPIRADO.

Inputs: transactionId, externalIdClient.

listAcquirerRoutesListar rotas de adquirenteA
Read-only

Lista as rotas de adquirente disponíveis para a conta ZuckPay autenticada (PSP, domínio de checkout, taxa de conversão recente), já filtradas por bloqueios/modo configurados na conta. Somente leitura — nunca retorna credenciais de adquirente.

Inputs: no named parameters.

listCoursesListar cursosA
Read-only

Lista os cursos (Meus Cursos / área de membros) dos quais o seller é dono na conta ZuckPay autenticada, com contagem de módulos/aulas/alunos. Somente leitura — não retorna dados de alunos matriculados.

Inputs: limit.

listInfractionsListar infrações e MEDA
Read-only

Lista chargebacks e pedidos de reembolso (Infrações e MED) da conta ZuckPay autenticada. Somente leitura. Documento e e-mail do comprador vêm sempre mascarados; nunca retorna o token de reembolso nem campos internos da triagem por IA.

Inputs: type, limit.

listIntegrationKeysListar chaves de integraçãoA
Read-only

Lista os metadados das chaves de integração (API keys) da conta ZuckPay autenticada: nome, domínio, client_id e data de criação. Somente leitura — NUNCA retorna o client_secret. Não existe tool para revelar, criar, rotacionar ou apagar chaves via MCP.

Inputs: no named parameters.

listProductsListar produtosA
Read-only

Lista os produtos cadastrados na conta ZuckPay autenticada (nome, preço, status, tipo). Somente leitura — não cria, edita nem exclui produtos.

Inputs: limit.

listSubscriptionsListar assinaturasA
Read-only

Lista as assinaturas (recorrências) da conta ZuckPay autenticada: produto, status (ativa/cancelada/inativa/pendente), valor, periodicidade e dados do assinante (mascarados). Somente leitura.

Inputs: limit.

listTransactionsListar transaçõesA
Read-only

Lista as transações da conta ZuckPay autenticada (vendas e saques), da mais recente para a mais antiga, com filtros por status, tipo, método de pagamento, ID externo e período (datas no horário de Brasília). Paginada por cursor: traga uma página por vez (padrão 20, máx 50) e use pagination.next_cursor para avançar — NÃO tente carregar tudo de uma vez.

Inputs: type, limit, cursor, status, +4 more.

listWebhooksListar webhooksA
Read-only

Lista os webhooks configurados na conta ZuckPay autenticada (nome, URL, eventos, status). Somente leitura — criação/exclusão de webhook não está disponível via MCP nesta fase.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 20 tools

    Disambiguation5/5

    Each tool targets a distinct resource or action (e.g., sales aggregates vs. individual transactions; different charge creation tools for PIX, SPEI, PayPal; separate list/get for products, courses, subscriptions, etc.). There is no ambiguity or overlap in purpose.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in camelCase (e.g., getSalesToday, createPixCharge, listTransactions). The verb always precedes the noun, with no mixing of conventions.

    Tool Count4/5

    20 tools cover a broad range of payment platform features. While slightly above the typical optimal range (3-15), the scope justifies the count. No tools are redundant; each serves a clear purpose.

    Completeness2/5

    The tool set is heavily read-only: most resources (products, courses, subscriptions, payment links, webhooks, etc.) lack create/update/delete operations. Only charges (PIX, SPEI, PayPal) can be created. This leaves significant gaps for common workflows like creating a product or managing subscriptions.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers