Servidor MCP WhatsApp | Awesome MCP Servers

Servidor WhatsApp MCP

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 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 Claude) quando o agente as acessa por meio das ferramentas (que você controla).

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

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

Atenção: como acontece com muitos servidores MCP, o WhatsApp MCP está sujeito à tríade letal. Isso significa que a injeção de projetos pode levar à exfiltração de dados privados.

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 não Opus. Sem o FFmpeg, você ainda pode enviar arquivos de áudio brutos usando a ferramenta send_file.

Passos

Clone este repositório

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

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ê executá-lo, 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, talvez seja necessário reautenticar.

Conecte-se ao servidor MCP

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

{
  "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

Reinicie o Claude Desktop / Cursor

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

Ou reinicie o Cursor.

Compatibilidade com Windows

Se você estiver executando este projeto no Windows, saiba que 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.

Passos para funcionar:

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

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:

Ponte Go WhatsApp (whatsapp-bridge/): Um aplicativo Go que se conecta à API web do WhatsApp, gerencia 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.
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 busca e recuperação eficientes

Uso

Uma vez conectado, 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 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 o envio e 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 maior compatibilidade, 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 mostrados ao imprimir mensagens que contêm 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

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

Solução de Problemas

Se você encontrar problemas de permissão ao executar o uv, talvez seja 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 o problema persistir, 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 o seu histórico de mensagens carregar, 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 mais soluções de problemas de integração do Claude Desktop, consulte a documentação do MCP. A documentação inclui dicas úteis para verificar logs e resolver problemas comuns.

WhatsApp MCP

Documentação