WhatsApp Meta Onboarding — MCP Server

#mcp #whatsapp-cloud-api #numero-virtual #coexistencia #meta-graph-api #onboarding

Apoie o projeto

Me pague um Café
_{QR Code Pix: abra o aplicativo do seu banco, escolha Pix > Ler QR Code e aponte a câmera.}

A imagem acima é um QR Code Pix. Se este guia poupou seu tempo, considere apoiar com um café. A contribuição ajuda a manter o projeto atualizado: acompanhar as mudanças da Meta na Cloud API e na Coexistência, registrar novas armadilhas e erros e incluir novas verificações.

Reclamações, ideias, falhas encontradas ou sugestões: contato@lumenaxis.dev.br

Servidor MCP (Model Context Protocol) que ensina o caminho completo para colocar um número de WhatsApp — inclusive um número virtual criado direto na Meta — enviando pela API oficial (Cloud API), cobre a Coexistência (app WhatsApp Business + API no mesmo número) e diagnostica cada etapa na Graph API.

O conteúdo nasceu de implantações reais (jul–out/2026), com todos os erros e becos sem saída do caminho. Cada armadilha vem marcada:

• vivido — aconteceu na prática, com a causa real e o que resolveu;
• doc-meta — vem da documentação pública da Meta; confirme na tela, porque a Meta muda.

Sumário

• O caminho
• Ferramentas
• Instalação
• Configuração
• Como usar
• Tags
• Segurança
• Estrutura do repositório
• Contribuir
• Créditos
• Licença

O caminho

flowchart TD
    A[1. Escolher o caminho] --> B[2. Portfólio + Verificação da empresa]
    B --> C[3. App no Meta for Developers]
    C --> D[4. WABA + número<br/>próprio ou virtual]
    D --> E[5. IDs certos<br/>WABA ID × Phone Number ID]
    E --> F[6. Usuário do Sistema<br/>+ token permanente]
    F --> G[7. Webhook<br/>callback + assinatura]
    G --> H[8. Moeda + pagamento]
    H --> I[9. Templates aprovados]
    I --> J[10. Primeiro envio ✅]
    A -.caminho C.-> K[11. Coexistência]
    K -.bloqueio da Meta.-> L[12. Suporte da Meta]

Referência completa em docs/: ferramentas · erros · glossário · tags.

Ferramentas

Ensino (offline, sem token)

Diagnóstico (Graph API, somente leitura)

Ações (alteram algo — exigem confirm=true)

Também expõe recursos (wa-guide://visao-geral, wa-guide://glossario, wa-guide://tags, wa-guide://erros, wa-guide://fase/{id}) e o prompt wa_conduzir_onboarding, que conduz a conversa fase a fase.

Instalação

Requer Node.js 20.3+.

git clone https://github.com/lucianumm/whatsApp-meta-onboarding-mcp-server.git
cd whatsApp-meta-onboarding-mcp-server
npm install
npm run check   # build + smoke test + docs

No npm 11+, se o tsx reclamar do esbuild, rode npm approve-scripts esbuild.

Configuração

Todas as variáveis são opcionais: sem nenhuma, as ferramentas de ensino funcionam. Veja .env.example.

Claude Code

claude mcp add whatsapp-meta --scope user -- node /caminho/para/whatsApp-meta-onboarding-mcp-server/dist/index.js

Para as ferramentas de rede, acrescente --env META_ACCESS_TOKEN=... você mesmo no terminal (o agente não digita segredos).

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "whatsapp-meta": {
      "command": "node",
      "args": ["/caminho/para/whatsApp-meta-onboarding-mcp-server/dist/index.js"],
      "env": {
        "META_ACCESS_TOKEN": "cole-aqui",
        "META_WABA_ID": "",
        "META_PHONE_NUMBER_ID": ""
      }
    }
  }
}

Como usar

Peça ao Claude em linguagem natural; ele escolhe as ferramentas:

• "Quero conectar um número virtual para disparos. Por onde começo?" → wa_guide_overview → wa_guide_get_phase
• "Em que ponto estou?" → wa_diagnose
• "Deu 131037 no envio." → wa_explain_error
• "Qual é o meu WABA ID de verdade?" → wa_discover_ids
• "Mandei mensagem e não chegou no sistema." → wa_check_webhook + wa_check_app_webhook
• "A coexistência ativou?" → wa_check_coexistence
• "Tudo sobre coisas irreversíveis." → wa_guide_search com tag: irreversivel

Ou use o prompt wa_conduzir_onboarding para um passo a passo guiado.

Tags

Vocabulário fechado, definido em src/knowledge/types.ts. Cada fase e cada erro tem as suas; o índice completo está em docs/tags.md.

Segurança

• O token nunca aparece em respostas nem em mensagens de erro (é removido antes de sair).
• Só duas ferramentas alteram algo, e ambas exigem confirm=true.
• O agente não digita tokens/App Secret/senhas, não cadastra cartão, não exclui portfólio/WABA/número e não aceita termos sem confirmação.
• Detalhes em SECURITY.md.

Estrutura do repositório

├── src/
│   ├── index.ts              # servidor: ferramentas, recursos, prompt (stdio)
│   ├── graph.ts              # cliente da Graph API, erros com dica, remoção de segredos
│   ├── api.ts                # chamadas tipadas (token, WABA, números, templates, webhook)
│   ├── knowledge/            # ← o conhecimento: edite aqui
│   │   ├── types.ts          #   tipos + vocabulário de tags
│   │   ├── phases.ts         #   as 12 fases (passos, checagens, armadilhas)
│   │   ├── errors.ts         #   catálogo de erros + glossário
│   │   └── render.ts         #   Markdown, busca, índice de tags
│   └── tools/                # ferramentas wa_* por domínio
├── scripts/
│   ├── smoke.ts              # teste ponta a ponta como cliente MCP
│   └── generate-docs.ts      # gera docs/ a partir de src/knowledge/
├── docs/                     # gerado — não edite à mão
├── evals/evaluation.xml      # perguntas de avaliação do MCP
├── imagens/                  # QR Code Pix "Me pague um Café"
└── .github/                  # CI, templates de issue e PR

Contribuir

Descobriu uma armadilha nova? Veja CONTRIBUTING.md — em resumo: acrescente em src/knowledge/, rode npm run check e faça commit de docs/ junto. O histórico de versões está no CHANGELOG.md.

Créditos

Criado e mantido por Lucianum — Instagram @lucianum · GitHub @lucianumm

Aviso

Projeto independente, sem vínculo com a Meta Platforms. WhatsApp, Meta e Facebook são marcas de seus respectivos donos. As telas e regras da Meta mudam com frequência: confirme no painel antes de qualquer ação irreversível.

Licença

Copyright (c) 2026 Lucianum.

Distribuído sob a Licença MIT: você pode usar, copiar, modificar e redistribuir livremente, inclusive para fins comerciais, desde que mantenha o aviso de copyright e a licença.