WhatsApp

Pesquise, leia e envie mensagens e contatos do WhatsApp. Requer uma ponte local Go WhatsApp.

GitHub
2
Experimente este MCPPatrocinado

Documentação

Servidor MCP do WhatsApp

Este é um servidor Model Context Protocol (MCP) para WhatsApp.

Com ele, você pode pesquisar e ler suas mensagens pessoais do WhatsApp (incluindo imagens, vídeos, documentos e mensagens de áudio), pesquisar seus contatos e enviar mensagens para indivíduos ou grupos. Você também pode enviar arquivos de mídia, incluindo imagens, vídeos, documentos e mensagens de áudio.

Ele se conecta diretamente à sua conta pessoal do WhatsApp por meio da API multidispositivo do WhatsApp Web (usando a biblioteca whatsmeow). Todas as suas mensagens são armazenadas localmente em um banco de dados SQLite e só são enviadas a um LLM (como o Claude) quando o agente as acessa por meio de ferramentas (que você controla).

Aqui está um exemplo do que você pode fazer quando ele está conectado ao Claude.

WhatsApp MCP

Para receber atualizações sobre este e outros projetos em que trabalho, insira seu e-mail aqui

Instalação

Pré-requisitos

  • Go
  • Python 3.6+
  • Aplicativo Anthropic Claude Desktop (ou Cursor)
  • UV (gerenciador de pacotes Python), instale com curl -LsSf https://astral.sh/uv/install.sh | sh
  • FFmpeg (opcional) - Necessário apenas para mensagens de áudio. Se você quiser enviar arquivos de áudio como mensagens de voz reproduzíveis do WhatsApp, eles devem estar no formato .ogg Opus. Com o FFmpeg instalado, o servidor MCP converterá automaticamente arquivos de áudio que não estejam no formato Opus. Sem o FFmpeg, você ainda pode enviar arquivos de áudio brutos usando a ferramenta send_file.

Etapas

  1. Clone este repositório

    git clone https://github.com/lharries/whatsapp-mcp.git
cd whatsapp-mcp

  2. Execute a ponte do WhatsApp

    Navegue até o diretório whatsapp-bridge e execute o aplicativo Go:

    cd whatsapp-bridge
go run main.go

    Na primeira vez que você executar, será solicitado a escanear um código QR. Escaneie o código QR com o aplicativo móvel do WhatsApp para autenticar.

    Após aproximadamente 20 dias, você pode precisar reautenticar.

  3. Conecte-se ao servidor MCP

    Copie o JSON abaixo com os valores {{PATH}} apropriados:

    {
  "mcpServers": {
    "whatsapp": {
      "command": "{{PATH_TO_UV}}", // Run `which uv` and place the output here
      "args": [
        "--directory",
        "{{PATH_TO_SRC}}/whatsapp-mcp/whatsapp-mcp-server", // cd into the repo, run `pwd` and enter the output here + "/whatsapp-mcp-server"
        "run",
        "main.py"
      ]
    }
  }
}

    Para Claude, salve isso como claude_desktop_config.json no diretório de configuração do Claude Desktop em:

    ~/Library/Application Support/Claude/claude_desktop_config.json

    Para Cursor, salve isso como mcp.json no diretório de configuração do Cursor em:

    ~/.cursor/mcp.json

  4. Reinicie o Claude Desktop / Cursor

    Abra o Claude Desktop e você deverá ver o WhatsApp como uma integração disponível.

    Ou reinicie o Cursor.

Compatibilidade com Windows

Se você estiver executando este projeto no Windows, esteja ciente de que o go-sqlite3 requer CGO habilitado para compilar e funcionar corretamente. Por padrão, o CGO está desabilitado no Windows, então você precisa habilitá-lo explicitamente e ter um compilador C instalado.

Etapas para fazer funcionar:

  1. Instale um compilador C
    Recomendamos usar o MSYS2 para instalar um compilador C para Windows. Após instalar o MSYS2, certifique-se de adicionar a pasta ucrt64\bin ao seu PATH.
    → Um guia passo a passo está disponível aqui.

  2. Habilite o CGO e execute o aplicativo

    cd whatsapp-bridge
go env -w CGO_ENABLED=1
go run main.go

Sem essa configuração, você provavelmente encontrará erros como:

Binary was compiled with 'CGO_ENABLED=0', go-sqlite3 requires cgo to work.

Visão Geral da Arquitetura

Este aplicativo consiste em dois componentes principais:

  1. Ponte Go do WhatsApp (whatsapp-bridge/): Um aplicativo Go que se conecta à API web do WhatsApp, lida com a autenticação via código QR e armazena o histórico de mensagens no SQLite. Ele serve como a ponte entre o WhatsApp e o servidor MCP.

  2. Servidor MCP Python (whatsapp-mcp-server/): Um servidor Python que implementa o Model Context Protocol (MCP), que fornece ferramentas padronizadas para o Claude interagir com os dados do WhatsApp e enviar/receber mensagens.

Armazenamento de Dados

  • Todo o histórico de mensagens é armazenado em um banco de dados SQLite dentro do diretório whatsapp-bridge/store/
  • O banco de dados mantém tabelas para conversas e mensagens
  • As mensagens são indexadas para pesquisa e recuperação eficientes

Uso

Uma vez conectado, você pode interagir com seus contatos do WhatsApp por meio do Claude, aproveitando os recursos de IA do Claude em suas conversas do WhatsApp.

Ferramentas MCP

O Claude pode acessar as seguintes ferramentas para interagir com o WhatsApp:

  • search_contacts: Pesquisar contatos por nome ou número de telefone
  • list_messages: Recuperar mensagens com filtros e contexto opcionais
  • list_chats: Listar conversas disponíveis com metadados
  • get_chat: Obter informações sobre uma conversa específica
  • get_direct_chat_by_contact: Encontrar uma conversa direta com um contato específico
  • get_contact_chats: Listar todas as conversas envolvendo um contato específico
  • get_last_interaction: Obter a mensagem mais recente com um contato
  • get_message_context: Recuperar o contexto em torno de uma mensagem específica
  • send_message: Enviar uma mensagem do WhatsApp para um número de telefone ou JID de grupo especificado
  • send_file: Enviar um arquivo (imagem, vídeo, áudio bruto, documento) para um destinatário especificado
  • send_audio_message: Enviar um arquivo de áudio como mensagem de voz do WhatsApp (requer que o arquivo seja um arquivo .ogg opus ou que o ffmpeg esteja instalado)
  • download_media: Baixar mídia de uma mensagem do WhatsApp e obter o caminho local do arquivo

Recursos de Manipulação de Mídia

O servidor MCP suporta tanto o envio quanto o recebimento de vários tipos de mídia:

Envio de Mídia

Você pode enviar vários tipos de mídia para seus contatos do WhatsApp:

  • Imagens, Vídeos, Documentos: Use a ferramenta send_file para compartilhar qualquer tipo de mídia suportado.
  • Mensagens de Voz: Use a ferramenta send_audio_message para enviar arquivos de áudio como mensagens de voz reproduzíveis do WhatsApp.
    • Para compatibilidade ideal, os arquivos de áudio devem estar no formato .ogg Opus.
    • Com o FFmpeg instalado, o sistema converterá automaticamente outros formatos de áudio (MP3, WAV, etc.) para o formato necessário.
    • Sem o FFmpeg, você ainda pode enviar arquivos de áudio brutos usando a ferramenta send_file, mas eles não aparecerão como mensagens de voz reproduzíveis.

Download de Mídia

Por padrão, apenas os metadados da mídia são armazenados no banco de dados local. A mensagem indicará que a mídia foi enviada. Para acessar essa mídia, você precisa usar a ferramenta download_media, que recebe o message_id e o chat_jid (que são exibidos ao imprimir mensagens contendo a mídia). Isso baixa a mídia e retorna o caminho do arquivo, que pode ser aberto ou passado para outra ferramenta.

Detalhes Técnicos

  1. O Claude envia solicitações ao servidor MCP Python
  2. O servidor MCP consulta a ponte Go para obter dados do WhatsApp ou diretamente o banco de dados SQLite
  3. O Go acessa a API do WhatsApp e mantém o banco de dados SQLite atualizado
  4. Os dados fluem de volta pela cadeia até o Claude
  5. Ao enviar mensagens, a solicitação flui do Claude através do servidor MCP até a ponte Go e para o WhatsApp

Solução de Problemas

  • Se você encontrar problemas de permissão ao executar o uv, pode ser necessário adicioná-lo ao seu PATH ou usar o caminho completo para o executável.
  • Certifique-se de que tanto o aplicativo Go quanto o servidor Python estejam em execução para que a integração funcione corretamente.

Problemas de Autenticação

  • Código QR Não Exibido: Se o código QR não aparecer, tente reiniciar o script de autenticação. Se os problemas persistirem, verifique se o seu terminal suporta a exibição de códigos QR.
  • WhatsApp Já Conectado: Se sua sessão já estiver ativa, a ponte Go se reconectará automaticamente sem exibir um código QR.
  • Limite de Dispositivos Atingido: O WhatsApp limita o número de dispositivos vinculados. Se você atingir esse limite, precisará remover um dispositivo existente do WhatsApp no seu telefone (Configurações > Dispositivos Vinculados).
  • Nenhuma Mensagem Carregando: Após a autenticação inicial, pode levar vários minutos para que seu histórico de mensagens seja carregado, especialmente se você tiver muitas conversas.
  • WhatsApp Fora de Sincronia: Se suas mensagens do WhatsApp ficarem fora de sincronia com a ponte, exclua ambos os arquivos de banco de dados (whatsapp-bridge/store/messages.db e whatsapp-bridge/store/whatsapp.db) e reinicie a ponte para reautenticar.

Para solução de problemas adicionais de integração com o Claude Desktop, consulte a documentação do MCP. A documentação inclui dicas úteis para verificar logs e resolver problemas comuns.