Sueth MCP WhatsApp
Connects to Meta's Graph API and WhatsApp webhooks for the WhatsApp Business Platform, supporting webhook verification, message event ingestion, and sending messages via Meta's API.
Integrates with the official Meta WhatsApp Business Cloud API to handle webhook events, store and search conversations, and prepare/confirm outbound text or template messages with human approval.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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
Ferramenta | Escopo OAuth | Finalidade |
verificar_status | whatsapp:read | Capacidades sem exibir segredos |
listar_conversas | whatsapp:read | Lista contatos vistos pelo webhook |
ler_conversa | whatsapp:read | Até 50 mensagens locais por contato |
buscar_mensagens | whatsapp:read | Pesquisa textual no histórico armazenado |
preparar_texto | whatsapp:send | Prévia da mensagem, sem enviar |
preparar_template | whatsapp:send | Template aprovado e sem parâmetros, sem enviar |
confirmar_envio | whatsapp:send | Confirma e realiza tentativa única de envio |
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: WhatsApp MCP
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 --> SQLiteA 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_mcpNo 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
No Meta for Developers, crie/configure um aplicativo com WhatsApp Business Platform e número vinculado.
Configure WHATSAPP_PHONE_NUMBER_ID e WHATSAPP_ACCESS_TOKEN. Em produção, prefira token de System User com permissões mínimas.
Cadastre https://SEU_DOMINIO/webhooks/whatsapp como callback de webhook, configure WHATSAPP_VERIFY_TOKEN e inscreva o campo messages.
Configure WHATSAPP_APP_SECRET (App Secret real), diferente do verify token, para a assinatura X-Hub-Signature-256.
Envie uma mensagem ao número Business. Apenas eventos novos começam a alimentar o banco.
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,5511888888888O 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 -dA 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 -qEstã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
Licença MIT. Projeto independente, sem afiliação à Meta, WhatsApp ou OpenAI.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Hosted WhatsApp MCP server: read, search and reply to your own WhatsApp chats from your AI.
Your own WhatsApp as an MCP server: read, search and send from any MCP client.
Hosted WhatsApp MCP server: send and read messages from your own linked number. OAuth sign-in.
Drive WhatsApp from any MCP client: pair devices, send text and media, manage contacts and groups.
Related MCP Servers
AlicenseNot gradedqualityFmaintenanceMCP server for interacting with the official Meta WhatsApp Business Platform/Cloud API, enabling sending messages, managing contacts, templates, and handling webhook callbacks.10 PyPIApache 2.0- AlicenseNot gradedqualityBmaintenanceEnables MCP clients to list, read, search, and send WhatsApp messages via a persistent WebSocket connection with local SQLite storage.49 npmAGPL 3.0
- AlicenseNot gradedqualityDmaintenanceA least-privilege, send-only MCP server for WhatsApp, backed by Meta's official WhatsApp Cloud API. It exposes tools to send text messages and pre-approved templates.8 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients to read WhatsApp chats and send, reply, react to, and schedule messages on the WhatsApp Desktop already logged in locally. All traffic stays on 127.0.0.1, with human-like pacing and verified delivery rather than cloud APIs or QR logins.2MIT