WhatsApp

Pesquise, leia e envie mensagens pessoais do WhatsApp, contatos e arquivos de mídia.

GitHub

Documentação

WhatsApp MCP Server

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 via API multidispositivo da web do WhatsApp (usando a biblioteca whatsmeow). Todas as suas mensagens são armazenadas localmente em um banco de dados SQLite e só são enviadas para um LLM (como 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 sejam Opus. Sem o FFmpeg, você ainda pode enviar arquivos de áudio brutos usando a ferramenta send_file.

Passos

  1. Clone este repositório

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

  2. Execute a ponte WhatsApp

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

    cd whatsapp-bridge
go run main.go

    Na primeira execução, você 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ê verá agora 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, portanto, você precisa habilitá-lo explicitamente e ter um compilador C instalado.

Passos para fazê-lo funcionar:

  1. Instale um compilador C
    Recomendamos usar 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 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 Python MCP (whatsapp-mcp-server/): Um servidor Python que implementa o Protocolo de Contexto do Modelo (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 busca e recuperação eficientes

Uso

Após a conexão, você pode interagir com seus contatos do WhatsApp através do Claude, aproveitando as capacidades 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 opcionais e contexto
  • 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 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 então retorna o caminho do arquivo, que pode ser aberto ou passado para outra ferramenta.

Detalhes Técnicos

  1. Claude envia solicitações para o servidor Python MCP
  2. O servidor MCP consulta a ponte Go para dados do WhatsApp ou diretamente ao 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 de 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 rodando 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 a sua sessão já estiver ativa, a ponte Go se reconectará automaticamente sem mostrar 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 os dois 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 adicional de integração com Claude Desktop, consulte a documentação do MCP. A documentação inclui dicas úteis para verificar logs e resolver problemas comuns.