WhatsApp Web

Um servidor MCP para interagir com o WhatsApp Web, permitindo enviar e receber mensagens.

GitHub
24
Experimente este MCPPatrocinado

Documentação

Muito Importante

A automação de mensagens do WhatsApp sem a API (Business) da Meta viola os Termos de Serviço do WhatsApp! Você assume total responsabilidade por tudo o que fizer com este MCP-Server. É possível que sua conta seja sinalizada/restrita.

MCP WhatsApp Web (TypeScript)

Um servidor Model Context Protocol (MCP) para WhatsApp Web, implementado em TypeScript. Este projeto é uma adaptação para TypeScript do repositório original whatsapp-mcp.

Com este servidor MCP, você pode:

  • Pesquisar e ler suas mensagens pessoais do WhatsApp (incluindo mídia)
  • Pesquisar seus contatos
  • Enviar mensagens para indivíduos ou grupos
  • Enviar e receber arquivos de mídia (imagens, vídeos, documentos, áudio)

image image

Recursos

  • Implementação em TypeScript: Base de código totalmente tipada para melhor experiência do desenvolvedor e confiabilidade do código
  • Backend WhatsApp selecionável: Usa whatsapp-web.js por padrão, com um backend opcional Baileys que roda sem navegador
  • Servidor MCP: Implementa o Model Context Protocol para integração perfeita com assistentes de IA
  • Suporte a mídia: Envie e receba imagens, vídeos, documentos e mensagens de áudio
  • Múltiplas opções de transporte: Suporta transportes stdio e HTTP Streamable — até ambos simultaneamente a partir de um único processo (inicie com stdio e defina MCP_HTTP_PORT para expor adicionalmente http://127.0.0.1:<port>/mcp, ou execute apenas com HTTP usando --http)
  • Autenticação flexível: Código QR (como ferramenta de imagem MCP), código de pareamento (ferramenta request_pairing_code, ou impresso automaticamente no stderr na inicialização via WHATSAPP_PAIRING_PHONE_NUMBER), e um fluxo OAuth opcional para clientes HTTP (MCP_OAUTH=true) onde a página de autorização do navegador mostra o código QR do WhatsApp — desvincular o WhatsApp revoga os tokens para que os clientes se reautentiquem automaticamente

Arquitetura

Este servidor MCP consiste em:

  1. Servidor MCP TypeScript: Implementa o Model Context Protocol para fornecer ferramentas padronizadas para assistentes de IA interagirem com o WhatsApp
  2. Backend WhatsApp: Uma interface de serviço compartilhada seleciona web.js/Puppeteer ou Baileys/WebSocket, gerencia autenticação e controla envio/recebimento de mensagens
  3. Implementações de ferramentas: Fornece várias ferramentas para contatos, conversas, mensagens, mídia e autenticação

Pré-requisitos

  • Node.js >= 22.0.0 (Node 22 ou 24 recomendado para a dependência SQLite do Baileys)
  • npm ou yarn
  • Para o backend padrão webjs: Google Chrome ou Microsoft Edge (detectado automaticamente; necessário para suporte a codec de vídeo/GIF; outras operações podem usar o Chromium incluído do Puppeteer)
  • Para baileys: instale dependências opcionais, incluindo o módulo nativo better-sqlite3. Nenhum Chrome, Edge ou Chromium é necessário em tempo de execução.

FFmpeg é incluído automaticamente via pacote npm ffmpeg-static — nenhuma instalação manual é necessária. Você pode apontar a variável de ambiente FFMPEG_PATH para seu próprio binário para substituí-lo.

Instalação

Instalação Manual

  1. Clone este repositório

    git clone https://github.com/mario-andreschak/mcp-whatsapp-web.git
cd mcp-whatsapp-web

  2. Instale as dependências

    npm install

  3. Compile o projeto

    npm run build

  4. Configure as variáveis de ambiente (opcional)

    Copie o arquivo de ambiente de exemplo e modifique conforme necessário:

    cp .env.example .env

    Você pode selecionar o backend com WHATSAPP_BACKEND, ajustar níveis de registro, fixar a versão do WhatsApp Web ou substituir o navegador detectado automaticamente (BROWSER_EXECUTABLE_PATH) e o binário ffmpeg (FFMPEG_PATH). WHATSAPP_HEADLESS=false mostra a janela do navegador web.js, e WHATSAPP_SESSION_DIR realoca seu perfil persistente. Use um diretório de sessão absoluto para mantê-lo consistente entre diretórios de trabalho.

Escolhendo um backend

WHATSAPP_BACKEND=webjs é o padrão e preserva sessões existentes e nomes de ferramentas MCP. Ele usa um perfil LocalAuth persistente dedicado, não seu perfil pessoal do Chrome. Agora mantém o user agent nativo do navegador e padrões gráficos, omite o banner de automação do Puppeteer e deixa o sandbox do navegador habilitado. Contêineres que exigem desabilitar o sandbox podem definir explicitamente WHATSAPP_NO_SANDBOX=true. Essas configurações não garantem que a automação seja indetectável.

Para usar o backend opcional Baileys, defina estas variáveis na configuração do seu cliente MCP ou .env, depois reinicie o servidor:

WHATSAPP_BACKEND=baileys
BAILEYS_SESSION_DIR=C:/path/to/your/baileys-sessions

BAILEYS_SESSION_DIR tem como padrão <working directory>/baileys-sessions; o exemplo acima deve ser substituído pelo seu próprio diretório absoluto. Vincule este backend separadamente com get_qr_code ou request_pairing_code. A opção existente WHATSAPP_PAIRING_PHONE_NUMBER também funciona. O Baileys não pode reutilizar o perfil do navegador web.js. Você pode voltar para webjs e retomar sua sessão existente.

Baileys e SQLite são dependências opcionais fixadas instaladas pelo npm install normal. Se seu gerenciador de pacotes as omitiu, execute npm install --include=optional. SQLite usa um addon nativo; um binário pré-compilado suportado ou uma cadeia de ferramentas de compilação nativa local é necessária. Para evitar baixar Chromium ao instalar para Baileys ou um navegador de sistema existente, use:

$env:PUPPETEER_SKIP_DOWNLOAD = 'true'
npm install --include=optional
npm run build

No macOS/Linux, o comando de instalação equivalente é PUPPETEER_SKIP_DOWNLOAD=true npm install --include=optional. Selecionar Baileys carrega apenas seu driver e nunca inicia ou limpa processos de navegador. Um backend indisponível produz um erro; ele nunca alterna drivers silenciosamente ou tenta reenviar por outro backend.

Sessões e histórico do Baileys

  • Credenciais, chaves Signal, contatos, conversas e mensagens persistem em BAILEYS_SESSION_DIR/session.sqlite. Mantenha todo o diretório privado e fora do controle de versão. Apenas um servidor em execução pode possuir um diretório de sessão. Use diretórios separados para contas independentes.
  • O desligamento normal preserva a sessão. Logout explícito ou autenticação inválida limpa as credenciais do Baileys e dados de conta em cache, e revoga seus tokens de acesso OAuth. O estado OAuth HTTP do Baileys é armazenado separadamente do web.js em BAILEYS_SESSION_DIR/oauth-store.json.
  • get_backend_status relata o backend ativo, autenticação, contagens de registros armazenados e estado de sincronização do histórico. Estar conectado não significa que o histórico terminou de chegar. Um estado de histórico available significa que os dados locais estão disponíveis, não que o WhatsApp forneceu um arquivo completo.
  • Ferramentas de contato e histórico consultam o armazenamento local sincronizado. A sincronização inicial completa do histórico é solicitada e pode levar tempo em contas grandes. list_messages pode solicitar até 100 mensagens mais antigas adicionais quando uma conversa conhecida tem menos do que o solicitado, com espera limitada e um cooldown por conversa. Lotes de histórico atrasados são persistidos para consultas subsequentes. O WhatsApp ainda pode fornecer apenas parte do histórico de uma conta.
  • Trate IDs de mensagem retornados como opacos e use IDs do backend ativo. Entradas legadas de número de telefone @c.us, @s.whatsapp.net, grupos e identificadores @lid são suportadas; mapeamentos LID/telefone conhecidos são persistidos. IDs de mensagem do web.js não podem ser passados para Baileys ou vice-versa.
  • Texto, mídia, downloads, notas de voz e as ferramentas de autenticação existentes usam a mesma interface MCP. Entradas de notas de voz devem ser arquivos locais ou base64; FFmpeg as converte para Opus/Ogg mono antes do envio. Se a conversão falhar, a ferramenta relata um erro sem enviar um tipo de mensagem diferente.

O backend Baileys é opcional e fixado em 7.0.0-rc14. Revise mudanças upstream antes de atualizar, especialmente migrações de autenticação e formato de mensagem. Veja a documentação do Baileys e o histórico de versões.

Instalação com FLUJO

FLUJO fornece um processo de instalação simplificado:

  1. Navegue até a seção MCP no FLUJO
  2. Clique em "Add Server"
  3. Copie e cole esta URL do repositório GitHub: https://github.com/mario-andreschak/mcp-whatsapp-web
  4. Clique em "Parse", "Clone", "Install", "Build" e "Update Server"

O FLUJO lidará automaticamente com a clonagem, instalação de dependências e processo de compilação para você.

Uso

Iniciando o Servidor MCP

npm start

Isso iniciará o servidor MCP usando transporte stdio por padrão, adequado para integração com Claude Desktop ou aplicativos similares.

Importante: Após iniciar o servidor pela primeira vez, você deve autenticar com o WhatsApp usando a ferramenta get_qr_code e escanear o código QR com seu telefone. Veja a seção Autenticação para instruções detalhadas.

Modo de Desenvolvimento

npm run dev

Isso inicia o servidor em modo de desenvolvimento com modo de observação TypeScript e reinicializações automáticas do servidor.

Depuração com MCP Inspector

npm run debug

Isso inicia a ferramenta MCP Inspector, que fornece uma interface web para testar e depurar seu servidor MCP. O inspector permite que você:

  • Veja todas as ferramentas disponíveis e seus esquemas
  • Execute ferramentas diretamente e veja suas respostas
  • Teste seu servidor sem precisar conectá-lo a um assistente de IA
  • Depure a execução de ferramentas e inspecione respostas

Conectando ao Claude Desktop

  1. Crie um arquivo de configuração para Claude Desktop:

    {
  "mcpServers": {
    "whatsapp": {
      "command": "node",
      "args": [
        "PATH_TO/dist/index.js"
      ]
    }
  }
}

    Substitua PATH_TO pelo caminho absoluto para o repositório.

  2. Salve isso como claude_desktop_config.json no seu diretório de configuração do Claude Desktop:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
    • Linux: ~/.config/Claude/claude_desktop_config.json

  3. Reinicie o Claude Desktop

Conectando ao Cursor

  1. Crie um arquivo de configuração para Cursor:

    {
  "mcpServers": {
    "whatsapp": {
      "command": "node",
      "args": [
        "PATH_TO/dist/index.js"
      ]
    }
  }
}

    Substitua PATH_TO pelo caminho absoluto para o repositório.

  2. Salve isso como mcp.json no seu diretório de configuração do Cursor:

    • macOS/Linux: ~/.cursor/mcp.json
    • Windows: %USERPROFILE%\.cursor\mcp.json

  3. Reinicie o Cursor

Autenticação

Na primeira vez que você executar o servidor, precisará autenticar com o WhatsApp:

  1. Inicie o servidor MCP
  2. Importante: Você deve usar a ferramenta get_qr_code para gerar um código QR
    • No Claude ou outros assistentes de IA, peça explicitamente para "usar a ferramenta get_qr_code para autenticar o WhatsApp"
    • O assistente chamará esta ferramenta e exibirá a imagem do código QR
  3. Escaneie o código QR com seu aplicativo móvel do WhatsApp
    • Abra o WhatsApp no seu telefone
    • Vá para Configurações > Aparelhos conectados > Conectar um aparelho
    • Aponte a câmera do seu telefone para o código QR exibido

Sua sessão será salva localmente no diretório whatsapp-sessions e será reutilizada automaticamente em execuções subsequentes. Se você não autenticar usando o código QR, não poderá usar nenhuma funcionalidade do WhatsApp.

Status de Autenticação e Logout

Você pode verificar seu status de autenticação atual e gerenciar sua sessão:

  • Use a ferramenta check_auth_status para verificar se você está autenticado atualmente
  • Se você precisar autenticar com uma conta diferente do WhatsApp ou reautenticar:
    1. Use a ferramenta logout para sair da sua sessão atual
    2. Em seguida, use a ferramenta get_qr_code para autenticar com um novo código QR

Isso é particularmente útil quando:

  • Você quer alternar entre diferentes contas do WhatsApp
  • Sua sessão expirou ou foi invalidada
  • Você está enfrentando problemas de conexão e precisa reautenticar

Ferramentas MCP Disponíveis

Autenticação

  • get_qr_code- Obtenha o código QR para autenticação do WhatsApp Web
  • check_auth_status- Verifique se você está autenticado atualmente com o WhatsApp
  • logout- Saia do WhatsApp e limpe a sessão atual

Contatos

  • search_contacts- Pesquise contatos por nome ou número de telefone
  • get_contact- Obtenha informações sobre um contato específico

Conversas

  • list_chats- Liste conversas disponíveis com metadados
  • get_chat- Obtenha informações sobre uma conversa específica
  • get_direct_chat_by_contact- Encontre uma conversa direta com um contato específico

Mensagens

  • list_messages- Recupere mensagens com filtros opcionais
  • get_message- Obtenha uma mensagem específica por ID
  • send_message- Envie uma mensagem de texto para uma conversa

Mídia

  • send_file- Envie um arquivo (imagem, vídeo, documento) para uma conversa
  • send_audio_message- Envie uma mensagem de áudio (nota de voz)
  • download_media- Baixe mídia de uma mensagem

Gerenciamento de Processos do Navegador

Este servidor MCP usa Puppeteer para controlar navegadores Chrome para a conectividade do WhatsApp Web. O servidor inclui um sistema robusto de gerenciamento de processos do navegador para evitar processos Chrome órfãos.

Limpeza Automática do Navegador

O servidor automaticamente:

  • Rastreia processos do navegador Chrome usando um sistema de rastreamento de PID
  • Limpa processos órfãos na inicialização
  • Fecha corretamente os processos do navegador durante o desligamento
  • Mantém um registro dos PIDs do navegador em .chrome-pids.json

Limpeza Manual do Navegador

Se você notar processos Chrome órfãos que não foram limpos automaticamente, você pode usar o utilitário de limpeza incluído:

npm run cleanup-browsers

Este utilitário irá:

  1. Verificar processos Chrome que possam estar relacionados ao WhatsApp Web
  2. Exibir uma lista de processos potencialmente órfãos
  3. Pedir confirmação antes de encerrá-los
  4. Limpar o arquivo de rastreamento de PID

Desenvolvimento

Estrutura do Projeto

  • src/index.ts - Ponto de entrada
  • src/server.ts - Implementação do servidor MCP
  • src/services/whatsapp.ts - Serviço do WhatsApp Web
  • src/tools/ - Implementações de ferramentas para vários recursos do WhatsApp
  • src/types/ - Definições de tipos TypeScript
  • src/utils/ - Funções utilitárias

Scripts

  • npm run build - Compilar o código TypeScript
  • npm run dev - Executar em modo de desenvolvimento com observação
  • npm run lint - Executar ESLint
  • npm run format - Formatar código com Prettier
  • npm run cleanup-browsers - Detectar e limpar processos Chrome órfãos
  • npm test - Executar a suíte de testes unitários (rápida, sem necessidade de navegador)
  • npm run test:watch - Executar testes unitários em modo de observação durante o desenvolvimento
  • npm run test:e2e - Compilar e depois executar testes de ponta a ponta (inicia o servidor real, incluindo um navegador headless)

Solução de Problemas

Problemas de Autenticação

  • Se o código QR não aparecer, tente reiniciar o servidor
  • Se você já estiver autenticado, nenhum código QR será exibido (use check_auth_status para verificar)
  • Se você precisar reautenticar, use a ferramenta logout primeiro e depois solicite um novo código QR
  • O WhatsApp limita o número de dispositivos vinculados; talvez seja necessário remover um dispositivo existente
  • Se você receber uma mensagem dizendo "Nenhum código QR está disponível no momento", mas você já estiver autenticado, isso é comportamento normal - use check_auth_status para confirmar seu status de autenticação

Problemas de Conexão

  • Certifique-se de ter uma conexão de internet estável
  • Se a conexão falhar, tente reiniciar o servidor
  • Verifique os logs para mensagens de erro detalhadas

Problemas com Processos do Navegador

  • Se você notar alto uso de CPU ou consumo de memória, pode haver processos Chrome órfãos
  • Execute npm run cleanup-browsers para detectar e limpar processos órfãos
  • Se o servidor travar com frequência, verifique se há processos órfãos e limpe-os
  • No Windows, você também pode usar o Gerenciador de Tarefas para procurar vários processos Chrome com "headless" na linha de comando
  • No Linux/macOS, use ps aux | grep chrome para verificar processos órfãos

Licença

MIT

Este projeto é um port para TypeScript do whatsapp-mcp original por lharries.