Hotmart Pro MCP

Servidor MCP (Model Context Protocol) em TypeScript com 31 tools opinativas sobre a API da Hotmart — vendas, comissões, reembolsos, assinaturas, cupons, produtos, área de membros (Club), eventos/ingressos e validação de webhooks. Feito para agentes de Claude Code operarem a Hotmart com segurança.

Diferente de um espelho cru da API: as tools carregam regra de negócio (nomes verbo_objeto em PT-BR, filtros úteis, paginação automática) e annotations MCP que marcam operações irreversíveis (reembolso, cancelamento, exclusão) para o agente pedir confirmação.

Recursos

• 🔐 OAuth2 client_credentials com cache do access_token e refresh automático (não reautentica a cada chamada)
• 🔁 Retry com backoff que respeita rate-limit (429) e reenvia apenas métodos idempotentes
• 📄 Paginação automática (todas=true) seguindo page_info.next_page_token
• 🛡️ Hardening: HTTPS obrigatório nas bases, cap de corpo de requisição, PII truncada em mensagens de erro
• 🏷️ Annotations readOnly / destructive em todas as tools
• 🧪 Testes com node:test

Tools

Vendas (Payments API)

| Tool | Descrição | |------|-----------| | listar_vendas | Histórico de vendas com filtros (produto, status, forma de pagamento, comprador, datas) | | resumo_vendas | Sumário de comissões/valores por moeda no período | | participantes_vendas | Compradores, produtores e afiliados de cada venda | | comissoes_vendas | Detalhamento de comissões por transação | | detalhes_preco_venda | Composição de preço (base, taxas, impostos, cupom) por venda | | obter_venda | Atalho: retorna 1 venda pelo código da transação, já desembrulhada | | reembolsar_venda 🔴 | Solicita reembolso de uma transação (irreversível) |

Assinaturas (Subscriptions API)

| Tool | Descrição | |------|-----------| | listar_assinaturas | Assinaturas com filtros (produto, status, plano, assinante) | | resumo_assinaturas | Visão agregada (métricas de recorrência) | | compras_assinatura | Histórico de compras de um assinante | | transacoes_assinatura | Transações de um assinante | | cancelar_assinatura 🔴 | Cancela uma ou várias assinaturas (lote, irreversível) | | cancelar_assinaturas_por_produto 🔴 | Cancela em lote todas as assinaturas de um produto — DRY-RUN por padrão (confirmar=true para efetivar) | | reativar_assinatura | Reativa assinatura(s) canceladas | | alterar_dia_cobranca | Muda o dia de vencimento da recorrência | | renegociar_assinatura | Cria parcelamento para assinante inadimplente |

Produtos (Products API)

| Tool | Descrição | |------|-----------| | listar_produtos | Catálogo de produtos (descobre ucode/product_id) | | listar_ofertas | Ofertas e preços de um produto | | listar_planos | Planos de assinatura de um produto | | obter_plano | Atalho: retorna 1 plano por id, código ou nome |

Cupons (Coupons API)

| Tool | Descrição | |------|-----------| | criar_cupom | Cria cupom de desconto (fração 0–1) para um produto | | listar_cupons | Lista cupons de um produto | | excluir_cupom 🔴 | Remove um cupom (irreversível) |

Área de membros (Club API)

| Tool | Descrição | |------|-----------| | listar_modulos | Módulos da área de membros | | listar_paginas | Páginas/aulas de um módulo | | listar_alunos | Alunos matriculados | | progresso_aluno | Progresso/conclusão de um aluno |

Eventos & Ingressos (Events API — ETICKET)

| Tool | Descrição | |------|-----------| | listar_eventos | Eventos da conta (descobre event_id) | | listar_ingressos | Ingressos vendidos (filtra por evento/comprador) | | participantes_evento | Participantes de um evento (com check-in) |

Webhooks / Hotconnect

| Tool | Descrição | |------|-----------| | verificar_hottok 🟢 | Valida o hottok de um webhook (timing-safe, sem rede) antes de processar o evento |

🔴 = destructiveHint — efeito imediato e irreversível. · 🟢 = tool local (sem chamada de rede).

Instalação

cd projects/hotmart-pro-mcp
npm install
npm run build

Configuração

Gere as credenciais no painel da Hotmart em Ferramentas → Credenciais de Desenvolvedor → Criar Credencial (ela devolve três valores: Client ID, Client Secret e Basic). Copie .env.example para .env e preencha:

| Variável | Obrigatória | Descrição | |----------|:-----------:|-----------| | HOTMART_CLIENT_ID | ✅ | Client ID da credencial | | HOTMART_CLIENT_SECRET | ✅ | Client Secret da credencial | | HOTMART_BASIC | ✅ | Token Basic (usado no OAuth2) | | HOTMART_ENV | — | sandbox (padrão) ou production | | HOTMART_CLUB_SUBDOMAIN | — | Subdomínio do Club (para as tools de área de membros) | | HOTMART_WEBHOOK_HOTTOK | — | hottok esperado do webhook (usado por verificar_hottok) | | HOTMART_PAYMENTS_BASE_URL / HOTMART_CLUB_BASE_URL | — | Sobrescreve as bases (derivadas do HOTMART_ENV) | | HOTMART_TOKEN_URL | — | Endpoint OAuth2 (padrão: api-sec-vlc.hotmart.com) | | HOTMART_MAX_RETRIES / HOTMART_TIMEOUT_MS | — | Ajustes de resiliência |

Testar localmente

npx @modelcontextprotocol/inspector dist/index.js

Adicionar ao Claude Code

Em .claude/settings.json → mcpServers:

"hotmart-pro": {
  "command": "npx",
  "args": ["-y", "hotmart-pro-mcp"],
  "env": {
    "HOTMART_CLIENT_ID": "seu-client-id",
    "HOTMART_CLIENT_SECRET": "seu-client-secret",
    "HOTMART_BASIC": "seu-basic",
    "HOTMART_ENV": "sandbox"
  }
}

Ou, rodando o build local:

"hotmart-pro": {
  "command": "node",
  "args": ["/caminho/absoluto/projects/hotmart-pro-mcp/dist/index.js"],
  "env": { "HOTMART_CLIENT_ID": "…", "HOTMART_CLIENT_SECRET": "…", "HOTMART_BASIC": "…" }
}

Adicionar ao Claude Desktop

Arquivo ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) ou %APPDATA%\Claude\claude_desktop_config.json (Windows), mesmo bloco acima.

Padrão event-driven (webhooks Hotconnect)

A Hotmart envia eventos (compra aprovada, reembolso, cancelamento, etc.) para uma URL de webhook que você cadastra no painel, junto de um hottok — o segredo que autentica que o evento veio mesmo da Hotmart.

Fluxo recomendado num n8n (ou qualquer endpoint):

1. Webhook node recebe o POST da Hotmart (payload traz o hottok).
2. Chame verificar_hottok com o hottok recebido — a tool compara (timing-safe, sem rede) contra o HOTMART_WEBHOOK_HOTTOK configurado e devolve { valid: true|false }.
3. Se valid=false, descarte o evento (possível forjado). Se valid=true, prossiga.
4. Enriqueça com as tools de leitura conforme o evento — ex.: obter_venda pela transação, compras_assinatura/transacoes_assinatura pelo assinante, participantes_evento por evento.

Configure o mesmo hottok do painel da Hotmart na variável HOTMART_WEBHOOK_HOTTOK (ou passe via argumento expected). A validação é local — nenhuma credencial ou dado sai da máquina.

Notas sobre a API

• A API pública da Hotmart é majoritariamente de leitura e gestão de vendas/assinaturas. Criação/edição de produtos é feita no painel (não exposta na API); por isso o CRUD completo aqui existe para cupons e o ciclo de assinaturas.
• As tools do Club exigem o subdomínio da sua área de membros (por argumento subdomain ou HOTMART_CLUB_SUBDOMAIN).
• As tools de eventos/ingressos cobrem apenas eventos ETICKET (não ONLINE_EVENT/cursos gravados).
• Datas de filtro são epoch em milissegundos (UTC), conforme a API.
• Campos não explícitos numa tool podem ser passados via filtros (query) ou camposExtras (corpo) — eles nunca sobrescrevem campos já validados.
• Alguns paths (reembolso, dia de cobrança, renegociação, eventos, cupons e as bases de sandbox) vêm de libs de referência, não da doc oficial — valide em sandbox antes de produção.

Segurança

• Credenciais só via variáveis de ambiente — nunca commitadas (.env no .gitignore).
• Bases não-HTTPS ou fora de *.hotmart.com são recusadas na inicialização (anti-SSRF/exfiltração de credencial).
• Operações irreversíveis são marcadas com destructiveHint; o cancelamento em lote por produto faz dry-run por padrão.
• verificar_hottok valida webhooks com comparação timing-safe e sem chamada de rede — o segredo esperado nunca é retornado.

Autor: Helbert Paranhos / Strat Academy · Licença MIT