whatsapp-mcp-server

@clickonsearch/whatsapp-mcp-server

Vincula uma conta pessoal do WhatsApp aos agentes deste repositório, da mesma forma que o WhatsApp Web faz — escaneie um QR code uma vez e ele permanece conectado. Normalmente você não executará isso diretamente; o README do whatsapp-agent informa quando iniciá-lo.

Atenção: esta não é a API oficial do WhatsApp Business — é uma biblioteca não oficial (Baileys) que automatiza uma conta pessoal, o que os termos do WhatsApp não cobrem realmente. O risco é baixo para uso pessoal normal, mas há uma pequena chance de a conta ser sinalizada.

whatsapp-agent (or any MCP client)
               │
               ▼
┌─────────────────────────────┐
│     whatsapp-mcp-server     │   Streamable HTTP MCP
└──────────────┬──────────────┘
               │
               ▼
┌─────────────────────────────┐
│           Baileys           │   WhatsApp Web protocol
└──────────────┬──────────────┘
               │
               ▼
your WhatsApp account

Executar

npx @clickonsearch/whatsapp-mcp-server

Na primeira vez, ele imprime um QR code — escaneie com seu celular: WhatsApp → Configurações → Aparelhos conectados → Conectar um aparelho. Depois disso, ele reconecta automaticamente, sem necessidade de escanear novamente (a menos que você desconecte o aparelho do seu celular).

Uma vez conectado, ele fica ouvindo em http://127.0.0.1:4100 para qualquer agente que você apontar para ele. Nenhuma variável de ambiente é necessária para testar — tudo abaixo tem um valor padrão.

Referência de configuração

Variável de ambiente	Padrão	Observações
PORT	4100
BIND_HOST	127.0.0.1	Quem pode conectar. O padrão significa apenas este computador
WHATSAPP_MCP_TOKEN	não definido	Segredo que todo chamador deve enviar. Obrigatório sempre que BIND_HOST não for 127.0.0.1
WHATSAPP_AUTH_DIR	./whatsapp-auth	Sua sessão — nunca compartilhe ou envie esta pasta para o repositório
BAILEYS_LOG_LEVEL	silent	Defina como info ou debug para ver detalhes da conexão

Permitindo que outra máquina conecte

Por padrão, apenas programas no mesmo computador podem acessar este servidor. Para permitir outros (um agente em um contêiner, ou em outra máquina), escolha um segredo e defina ambos:

export WHATSAPP_MCP_TOKEN=$(openssl rand -hex 32)
BIND_HOST=0.0.0.0 npx @clickonsearch/whatsapp-mcp-server

Dê ao whatsapp-agent o mesmo WHATSAPP_MCP_TOKEN e ele o enviará automaticamente. O servidor se recusa a iniciar em qualquer outro endereço sem um token. Qualquer pessoa com o token pode ler suas conversas e enviar mensagens como você, então trate-o como uma senha — e, como ele trafega por HTTP simples, use apenas em uma rede confiável ou atrás de TLS (por exemplo, um proxy reverso).

O que ele expõe

Ferramenta	O que faz
send_message	Envia uma mensagem de texto para um número de telefone ou conversa
list_chats	Lista conversas vistas desde a conexão (inclui o histórico recente do próprio WhatsApp)
get_recent_messages	Obtém mensagens recentes de uma conversa (até 200, apenas em memória)
search_contacts	Encontra um contato por nome ou número

---

Para desenvolvedores

Executando a partir do código-fonte:

cd mcp-servers/whatsapp-mcp-server
npm install
cp .env.example .env
npm run dev

Isso roda como um servidor MCP padrão (Streamable HTTP em /mcp), então qualquer ponte deste repositório pode conectar-se a ele sem tratamento especial — ele apenas precisava falar o mesmo protocolo que o servidor MCP remoto do próprio GitHub usa. Ele também expõe GET /events (um fluxo SSE simples de mensagens recebidas) e GET /health ({ ok, connected, self }) para qualquer coisa que queira reagir a mensagens em tempo real, como o whatsapp-agent faz.

import { WhatsAppConnection } from "./src/whatsapp.js";
import { createServer } from "./src/server.js";

const whatsapp = new WhatsAppConnection("./whatsapp-auth");
await whatsapp.start();

const app = createServer(whatsapp);
app.listen(4100);