WhatsApp (TypeScript/Baileys)

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

GitHub
1
Experimente este MCPPatrocinado

Documentação

WhatsApp MCP Server (TypeScript/Baileys)

smithery badge

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

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

  • Pesquise suas mensagens pessoais do WhatsApp.
  • Pesquise seus contatos (indivíduos, 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 detalhes 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 do WhatsApp para "Meu amor" no WhatsApp dizendo "Te amo"

Assistente: Ok, preciso encontrar o contato primeiro. Usando a 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 a 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: Pesquise contatos por nome ou parte do número de telefone (JID).
  • list_messages: Recupere o histórico de mensagens de um chat específico, com paginação.
  • list_chats: Liste seus chats, ordenáveis por atividade ou nome, filtráveis, paginados, opcionalmente inclui detalhes da última mensagem.
  • get_chat: Obtenha informações detalhadas sobre um chat específico.
  • get_message_context: Recupere mensagens enviadas imediatamente antes e depois de um ID de mensagem específico para contexto.
  • send_message: Envie 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 integrado inicial a TypeScript e SQLite)
  • npm (ou yarn/pnpm): Geralmente vem com o Node.js.
  • Cliente de IA: Aplicativo Anthropic Claude Desktop, 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 seu aplicativo móvel do WhatsApp (Configurações > Dispositivos vinculados > Vincular um dispositivo).
    • As credenciais de autenticação serão salvas localmente no diretório auth_info/ (isso é 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 do 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

Quando 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 pela interface de chat do agente. Peça para 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, lidando com 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 do Baileys para enviar mensagens.
  5. Usa pino para registrar atividade (wa-logs.txt para eventos do WhatsApp, mcp-logs.txt para atividade 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 chat 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 Grande (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 incluído)
  • Registro de logs: pino
  • Validação de esquema: zod (para entradas de ferramentas MCP)

Solução de Problemas

  • Problemas com 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 telefone.
  • Falhas de Autenticação / Sessão Encerrada:
    • Se a conexão fechar com um erro DisconnectReason.loggedOut, você precisa 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 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 esteja 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).