WhatsApp

Conecte sua conta pessoal do WhatsApp a um agente de IA usando a API multi-dispositivo do WhatsApp Web.

GitHub
72
Experimente este MCPPatrocinado

Documentação

Servidor MCP do WhatsApp (TypeScript/Baileys)

smithery badge

Este é um servidor Model Context Protocol (MCP) para WhatsApp, construído com TypeScript e utilizando a biblioteca @whiskeysockets/baileys.

Ele permite conectar sua conta pessoal do WhatsApp a um agente de IA (como o Anthropic Claude via aplicativo desktop ou Cursor), permitindo que ele:

  • Pesquise suas mensagens pessoais do WhatsApp.
  • Pesquise seus contatos (individuais, não grupos).
  • Liste seus chats recentes.
  • Recupere o histórico de mensagens de chats específicos.
  • Envie mensagens para indivíduos ou grupos.

Ele se conecta diretamente à sua conta pessoal do WhatsApp usando a API multi-dispositivo do WhatsApp Web. Todas as suas mensagens e dados de autenticação são armazenados localmente em um banco de dados SQLite (./data/) e cache de autenticação (./auth_info/). Os dados só são enviados ao agente de IA conectado quando ele usa explicitamente as ferramentas MCP fornecidas (que você controla pela interface do agente).

(Opcional: Considere adicionar uma captura de tela ou GIF semelhante ao exemplo de referência aqui)

Exemplo

Usuário: Envie uma mensagem de whatsapp para "Meu amor" no whatsapp dizendo "Te amo"

Assistente: Ok, preciso encontrar o contato primeiro. Usando ferramenta: whatsapp.search_contacts

{
  "query": "Meu amor"
}

Resultado da Ferramenta:

[
  {
    "jid": "5599xxxxxx@s.whatsapp.net",
    "name": "Meu Amor"
  }
]

Assistente: Contato encontrado. Agora enviando a mensagem. Usando ferramenta: whatsapp.send_message

{
  "recipient": "5599xxxxxx@s.whatsapp.net",
  "message": "Te amo"
}

Resultado da Ferramenta:

Message sent successfully to 5599xxxxxx@s.whatsapp.net (ID: XXXXXXXXXXX).

Principais Recursos (Ferramentas MCP)

O servidor expõe as seguintes ferramentas ao agente de IA conectado:

  • search_contacts: Pesquisar contatos por nome ou parte do número de telefone (JID).
  • list_messages: Recuperar o histórico de mensagens de um chat específico, com paginação.
  • list_chats: Listar seus chats, ordenáveis por atividade ou nome, filtráveis, paginados, opcionalmente inclui detalhes da última mensagem.
  • get_chat: Obter informações detalhadas sobre um chat específico.
  • get_message_context: Recuperar mensagens enviadas imediatamente antes e depois de um ID de mensagem específico para contexto.
  • send_message: Enviar uma mensagem de texto para um JID de destinatário especificado (usuário ou grupo).

Instalação

Instalando via Smithery

Para instalar o WhatsApp MCP Server para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @jlucaso1/whatsapp-mcp-ts --client claude

Pré-requisitos

  • Node.js: Versão 23.10.0 ou superior (conforme especificado em package.json). Você pode verificar sua versão com node -v. (Possui suporte inicial integrado a TypeScript e SQLite)
  • npm (ou yarn/pnpm): Geralmente vem com o Node.js.
  • Cliente de IA: Aplicativo desktop Anthropic Claude, Cursor, Cline ou Roo Code (ou outro cliente compatível com MCP).

Passos

  1. Clone este repositório:

    git clone <your-repo-url> whatsapp-mcp-ts
cd whatsapp-mcp-ts

  2. Instale as dependências:

    npm install
# or yarn install / pnpm install

  3. Execute o servidor pela primeira vez: Use node para executar o script principal diretamente.

    node src/main.ts
    • Na primeira execução, ele provavelmente gerará um link de código QR usando quickchart.io e tentará abri-lo no seu navegador padrão.
    • Escaneie este código QR usando o aplicativo móvel do WhatsApp (Configurações > Aparelhos conectados > Conectar um aparelho).
    • As credenciais de autenticação serão salvas localmente no diretório auth_info/ (ignorado pelo git).
    • As mensagens começarão a sincronizar e serão armazenadas em ./data/whatsapp.db. Isso pode levar algum tempo dependendo do tamanho do seu histórico. Verifique o wa-logs.txt e a saída do console para acompanhar o progresso.
    • Mantenha esta janela de terminal aberta. Após a sincronização, você pode fechá-la.

Configuração para o Cliente de IA

Você precisa informar ao seu cliente de IA como iniciar este servidor MCP.

  1. Prepare o JSON de configuração: Copie a seguinte estrutura JSON. Você precisará substituir {{PATH_TO_REPO}} pelo caminho absoluto do diretório onde você clonou este repositório.

    {
  "mcpServers": {
    "whatsapp": {
      "command": "node",
      "args": [
        "{{PATH_TO_REPO}}/src/main.ts"
      ],
      "timeout": 15, // Optional: Adjust startup timeout if needed
      "disabled": false
    }
  }
}
    • Obtenha o caminho absoluto: Navegue até o diretório whatsapp-mcp-ts no seu terminal e execute pwd. Use esta saída para {{PATH_TO_REPO}}.

  2. Salve o arquivo de configuração:

    • Para Claude Desktop: Salve o JSON como claude_desktop_config.json no diretório de configuração:
      • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
      • Windows: %APPDATA%\Claude\claude_desktop_config.json (Caminho provável, verifique se necessário)
      • Linux: ~/.config/Claude/claude_desktop_config.json (Caminho provável, verifique se necessário)
    • Para Cursor: Salve o JSON como mcp.json no diretório de configuração:
      • ~/.cursor/mcp.json

  3. Reinicie o Claude Desktop / Cursor: Feche e reabra seu cliente de IA. Ele agora deve detectar o servidor MCP "whatsapp" e permitir que você use suas ferramentas.

Uso

Depois que o servidor estiver em execução (manualmente via node src/main.ts ou iniciado pelo cliente de IA via arquivo de configuração) e conectado ao seu cliente de IA, você pode interagir com seus dados do WhatsApp através da interface de chat do agente. Peça para ele pesquisar contatos, listar chats recentes, ler mensagens ou enviar mensagens.

Visão Geral da Arquitetura

Este aplicativo é um único processo Node.js que:

  1. Usa @whiskeysockets/baileys para se conectar à API do WhatsApp Web, gerenciando autenticação e eventos em tempo real.
  2. Armazena chats e mensagens do WhatsApp localmente em um banco de dados SQLite (./data/whatsapp.db) usando node:sqlite.
  3. Executa um servidor MCP usando @modelcontextprotocol/sdk que escuta requisições de um cliente de IA via entrada/saída padrão (stdio).
  4. Fornece ferramentas MCP que consultam o banco de dados SQLite local ou usam o socket Baileys para enviar mensagens.
  5. Usa pino para registrar atividades (wa-logs.txt para eventos do WhatsApp, mcp-logs.txt para atividades do servidor MCP).

Armazenamento de Dados e Privacidade

  • Autenticação: Suas credenciais de conexão do WhatsApp são armazenadas localmente no diretório ./auth_info/.
  • Mensagens e Chats: Seu histórico de mensagens e metadados de chats são armazenados localmente no arquivo SQLite ./data/whatsapp.db.
  • Dados Locais: Tanto auth_info/ quanto data/ estão incluídos em .gitignore para evitar commits acidentais. Trate esses diretórios como sensíveis.
  • Interação com LLM: Os dados só são enviados ao Modelo de Linguagem de Grande Escala (LLM) conectado quando o agente de IA usa ativamente uma das ferramentas MCP fornecidas (por exemplo, list_messages, send_message). O servidor em si não envia proativamente seus dados para nenhum outro lugar.

Detalhes Técnicos

  • Linguagem: TypeScript
  • Runtime: Node.js (>= v23.10.0)
  • API do WhatsApp: @whiskeysockets/baileys
  • SDK MCP: @modelcontextprotocol/sdk
  • Banco de Dados: node:sqlite (SQLite integrado)
  • Registro de Logs: pino
  • Validação de Esquema: zod (para entradas das ferramentas MCP)

Solução de Problemas

  • Problemas com o Código QR:
    • Se o link do código QR não abrir automaticamente, verifique a saída do console para a URL quickchart.io e abra-a manualmente.
    • Certifique-se de escanear o código QR prontamente com o aplicativo WhatsApp do seu celular.
  • Falhas de Autenticação / Sessão Encerrada:
    • Se a conexão fechar com um erro DisconnectReason.loggedOut, você precisará reautenticar. Pare o servidor, exclua o diretório ./auth_info/ e reinicie o servidor (node src/main.ts) para obter um novo código QR.
  • Problemas de Sincronização de Mensagens:
    • A sincronização inicial pode levar tempo. Verifique wa-logs.txt para ver a atividade.
    • Se as mensagens parecerem dessincronizadas ou ausentes, talvez seja necessário um reset completo. Pare o servidor, exclua ambos os diretórios ./auth_info/ e ./data/, e reinicie o servidor para reautenticar e ressincronizar o histórico.
  • Problemas de Conexão MCP (Claude/Cursor):
    • Verifique novamente o command e o args (especialmente o {{PATH_TO_REPO}}) no seu claude_desktop_config.json ou mcp.json. Certifique-se de que o caminho seja absoluto e correto.
    • Verifique se o Node.js está instalado corretamente e no PATH do seu sistema.
    • Verifique os logs do cliente de IA para erros relacionados à inicialização do servidor MCP.
    • Verifique os logs deste servidor (mcp-logs.txt) para erros relacionados ao MCP.
  • Erros ao Enviar Mensagens:
    • Certifique-se de que o JID do destinatário está correto (por exemplo, number@s.whatsapp.net para usuários, groupid@g.us para grupos).
    • Verifique wa-logs.txt para erros específicos do Baileys.
  • Problemas Gerais: Verifique tanto wa-logs.txt quanto mcp-logs.txt para mensagens de erro detalhadas.

Para problemas adicionais de integração MCP, consulte a documentação oficial do MCP.

Créditos

Licença

Este projeto está licenciado sob a Licença ISC (veja package.json).