Sueth MCP WhatsApp

Servidor MCP independente para integração com a WhatsApp Business Cloud API oficial da Meta, desenvolvido em Python com MCP Streamable HTTP e SQLite.

Importante: este conector não lê WhatsApp pessoal, não utiliza WhatsApp Web e não recupera histórico anterior à ativação do webhook. O número precisa estar vinculado à WhatsApp Business Platform. O suporte a operações de escrita no ChatGPT depende do plano e das permissões.

Funcionalidades da V0.1

Rotas HTTP: GET /healthz, GET/POST /webhooks/whatsapp e /mcp.

O webhook verifica desafio e HMAC SHA-256, usa ID da mensagem para deduplicação e salva texto, contato, tipo, direção, data e status em SQLite. Anexos não são baixados.

Related MCP server: lingtai-whatsapp

Arquitetura

ChatGPT / cliente MCP
    | Authorization Code + PKCE / OAuth externo
    v
Proxy HTTPS ----> /mcp ----> Ferramentas / Banco SQLite
                                    |
                               Meta Graph API

Meta WhatsApp Webhook assinado ---> /webhooks/whatsapp --> SQLite

A autenticação remota exige JWT RS256 emitido por um provedor OAuth/OIDC, validação de issuer, audience, expiração, subject e scopes. O código não emite tokens OAuth. O token da Meta fica somente no servidor.

Execução local em Windows PowerShell

git clone https://github.com/Matheus-Sueth/MCPWhatsApp.git
cd MCPWhatsApp
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[test]"
Copy-Item .env.example .env
# Preencher .env com os dados da Meta
python -m whatsapp_mcp

No modo local, acesse http://127.0.0.1:8000/mcp e http://127.0.0.1:8000/healthz.

O modo local não exige OAuth e NUNCA deve ser exposto por proxy, túnel, internet, NAT ou rede de produção. Para usar o ChatGPT remotamente, selecione MCP_AUTH_MODE=oauth e configure o IdP antes do deploy.

Configuração da Meta

1. No Meta for Developers, crie/configure um aplicativo com WhatsApp Business Platform e número vinculado.

2. Configure WHATSAPP_PHONE_NUMBER_ID e WHATSAPP_ACCESS_TOKEN. Em produção, prefira token de System User com permissões mínimas.

3. Cadastre https://SEU_DOMINIO/webhooks/whatsapp como callback de webhook, configure WHATSAPP_VERIFY_TOKEN e inscreva o campo messages.

4. Configure WHATSAPP_APP_SECRET (App Secret real), diferente do verify token, para a assinatura X-Hub-Signature-256.

5. Envie uma mensagem ao número Business. Apenas eventos novos começam a alimentar o banco.

6. Ajuste WHATSAPP_GRAPH_VERSION para a versão efetivamente suportada pelo seu aplicativo.

A mensagem de texto livre só pode ser enviada a um contato se houve mensagem recebida dele nas últimas 24 horas. Para iniciar contato fora desta janela, use um template aprovado pela Meta.

Envio com confirmação

Por padrão MCP_ENABLE_SEND=false. Para testar envio com uma conta autorizada:

MCP_ENABLE_SEND=true
MCP_ALLOWED_RECIPIENTS=5511999999999,5511888888888

O fluxo exige preparar_texto ou preparar_template, visualizar a prévia, obter aprovação explícita do usuário e executar confirmar_envio com token_aprovacao e confirmacao_usuario igual a CONFIRMO. A reserva do token é atômica e só pode ser usada uma vez. A confirmação enviada pelo modelo não substitui a aprovação humana da interface de ChatGPT.

Não há retry automático de envio, pois um timeout pode representar entrega incerta. Não use mensagens em massa ou spam.

Deploy em Docker

cp .env.example .env
# Ajuste OAuth, Meta e MCP_BIND_HOST=0.0.0.0 no arquivo .env para ambiente remoto
mkdir -p data
# Linux: chown 10001:10001 data && chmod 700 data
docker compose up --build -d

A porta publicada pelo compose fica em 127.0.0.1:8000 na VPS. Use proxy HTTPS com domínio e Host preservado. Consulte docs/CONFIGURACAO_CHATGPT.md.

Testes

pip install -e ".[test]"
pytest -q

Estão incluídos testes unitários de HMAC, SQLite, idempotência, janela de atendimento e validação de configuração. A integração de ponta a ponta com a Meta e com um IdP real exige credenciais e ambiente de homologação.

Documentação

• Configuração ChatGPT e OAuth

• Segurança e privacidade

• Roadmap

Licença MIT. Projeto independente, sem afiliação à Meta, WhatsApp ou OpenAI.