WhatsApp Web MCP

Conecta modelos de IA ao WhatsApp Web usando o Model Context Protocol (MCP) para automatizar e aprimorar interações.

Documentação

WhatsApp Web MCP

Uma ponte poderosa entre o WhatsApp Web e modelos de IA usando o Model Context Protocol (MCP). Este projeto permite que modelos de IA como o Claude interajam com o WhatsApp através de uma interface padronizada, facilitando a automação e o aprimoramento das interações com o WhatsApp de forma programática.

Visão Geral

O WhatsApp Web MCP fornece uma integração perfeita entre o WhatsApp Web e modelos de IA ao:

Criar uma interface padronizada através do Model Context Protocol (MCP)
Oferecer acesso ao servidor MCP para funcionalidades do WhatsApp
Fornecer opções flexíveis de implantação através dos modos SSE ou Command
Suportar tanto a integração direta com o cliente WhatsApp quanto a conectividade baseada em API

Aviso Legal

IMPORTANTE: Esta ferramenta é apenas para fins de teste e não deve ser usada em ambientes de produção.

Aviso legal do projeto WhatsApp Web:

Este projeto não é afiliado, associado, autorizado, endossado por, ou de qualquer forma oficialmente conectado ao WhatsApp ou a qualquer uma de suas subsidiárias ou afiliadas. O site oficial do WhatsApp pode ser encontrado em whatsapp.com. "WhatsApp" bem como nomes relacionados, marcas, emblemas e imagens são marcas registradas de seus respectivos proprietários. Também não é garantido que você não será bloqueado ao usar este método. O WhatsApp não permite bots ou clientes não oficiais em sua plataforma, portanto isso não deve ser considerado totalmente seguro.

Instalação

Clone o repositório:

git clone https://github.com/pnizer/wweb-mcp.git
cd wweb-mcp

Instale globalmente ou use com npx:

# Install globally
npm install -g .

# Or use with npx directly
npx .

Compile com Docker:
```
docker build . -t wweb-mcp:latest
```

Configuração

Opções de Linha de Comando

Opção	Alias	Descrição	Escolhas	Padrão
`--mode`	`-m`	Modo de execução	`mcp`, `whatsapp-api`	`mcp`
`--mcp-mode`	`-c`	Modo de conexão MCP	`standalone`, `api`	`standalone`
`--transport`	`-t`	Modo de transporte MCP	`sse`, `command`	`sse`
`--sse-port`	`-p`	Porta para o servidor SSE	-	`3002`
`--api-port`	-	Porta para o servidor da API do WhatsApp	-	`3001`
`--auth-data-path`	`-a`	Caminho para armazenar dados de autenticação	-	`.wwebjs_auth`
`--auth-strategy`	`-s`	Estratégia de autenticação	`local`, `none`	`local`
`--api-base-url`	`-b`	URL base da API para MCP ao usar o modo api	-	`http://localhost:3001/api`
`--api-key`	`-k`	Chave da API para a API REST do WhatsApp Web ao usar o modo api	-	`''`

Autenticação por Chave de API

Ao executar no modo API, o servidor da API do WhatsApp exige autenticação usando uma chave de API. A chave de API é gerada automaticamente quando você inicia o servidor da API do WhatsApp e é exibida nos logs:

WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

Para conectar o servidor MCP ao servidor da API do WhatsApp, você precisa fornecer esta chave de API usando a opção --api-key ou -k:

npx wweb-mcp --mode mcp --mcp-mode api --api-base-url http://localhost:3001/api --api-key 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

A chave de API é armazenada no diretório de dados de autenticação (especificado por --auth-data-path) e persiste entre reinicializações do servidor da API do WhatsApp.

Métodos de Autenticação

Autenticação Local (Recomendada)

Escaneie o código QR uma vez
As credenciais persistem entre sessões
Mais estável para operação de longo prazo

Sem Autenticação

Método padrão
Requer escaneamento do código QR a cada inicialização
Adequado para testes e desenvolvimento

Uso

Modos de Execução

Servidor da API do WhatsApp

Execute um servidor independente da API do WhatsApp que expõe funcionalidades do WhatsApp através de endpoints REST:

npx wweb-mcp --mode whatsapp-api --api-port 3001

Servidor MCP (Independente)

Execute um servidor MCP que se conecta diretamente ao WhatsApp Web:

npx wweb-mcp --mode mcp --mcp-mode standalone --transport sse --sse-port 3002

Servidor MCP (Cliente de API)

Execute um servidor MCP que se conecta ao servidor da API do WhatsApp:

# First, start the WhatsApp API server and note the API key from the logs
npx wweb-mcp --mode whatsapp-api --api-port 3001

# Then, start the MCP server with the API key
npx wweb-mcp --mode mcp --mcp-mode api --api-base-url http://localhost:3001/api --api-key YOUR_API_KEY --transport sse --sse-port 3002

Ferramentas Disponíveis

Ferramenta	Descrição	Parâmetros
`get_status`	Verifica o status da conexão do cliente WhatsApp	Nenhum
`send_message`	Envia mensagens para contatos do WhatsApp	`number`: Número de telefone para envio `message`: Conteúdo de texto para envio
`search_contacts`	Busca contatos por nome ou número	`query`: Termo de busca para encontrar contatos
`get_messages`	Recupera mensagens de um chat específico	`number`: Número de telefone para obter mensagens `limit` (opcional): Número de mensagens a recuperar
`get_chats`	Obtém uma lista de todos os chats do WhatsApp	Nenhum
`create_group`	Cria um novo grupo no WhatsApp	`name`: Nome do grupo `participants`: Matriz de números de telefone para adicionar
`add_participants_to_group`	Adiciona participantes a um grupo existente	`groupId`: ID do grupo `participants`: Matriz de números de telefone para adicionar
`get_group_messages`	Recupera mensagens de um grupo	`groupId`: ID do grupo `limit` (opcional): Número de mensagens a recuperar
`send_group_message`	Envia uma mensagem para um grupo	`groupId`: ID do grupo `message`: Conteúdo de texto para envio
`search_groups`	Busca grupos por nome, descrição ou nomes de membros	`query`: Termo de busca para encontrar grupos
`get_group_by_id`	Obtém informações detalhadas sobre um grupo específico	`groupId`: ID do grupo para obter

Recursos Disponíveis

URI do Recurso	Descrição
`whatsapp://contacts`	Lista de todos os contatos do WhatsApp
`whatsapp://messages/{number}`	Mensagens de um chat específico
`whatsapp://chats`	Lista de todos os chats do WhatsApp
`whatsapp://groups`	Lista de todos os grupos do WhatsApp
`whatsapp://groups/search`	Busca grupos por nome, descrição ou nomes de membros
`whatsapp://groups/{groupId}/messages`	Mensagens de um grupo específico

Endpoints da API REST

Contatos e Mensagens

Endpoint	Método	Descrição	Parâmetros
`/api/status`	GET	Obtém o status da conexão do WhatsApp	Nenhum
`/api/contacts`	GET	Obtém todos os contatos	Nenhum
`/api/contacts/search`	GET	Busca contatos	`query`: Termo de busca
`/api/chats`	GET	Obtém todos os chats	Nenhum
`/api/messages/{number}`	GET	Obtém mensagens de um chat	`limit` (consulta): Número de mensagens
`/api/send`	POST	Envia uma mensagem	`number`: Destinatário `message`: Conteúdo da mensagem

Gerenciamento de Grupos

Endpoint	Método	Descrição	Parâmetros
`/api/groups`	GET	Obtém todos os grupos	Nenhum
`/api/groups/search`	GET	Busca grupos	`query`: Termo de busca
`/api/groups/create`	POST	Cria um novo grupo	`name`: Nome do grupo `participants`: Matriz de números
`/api/groups/{groupId}`	GET	Obtém informações detalhadas sobre um grupo específico	Nenhum
`/api/groups/{groupId}/messages`	GET	Obtém mensagens de um grupo	`limit` (consulta): Número de mensagens
`/api/groups/{groupId}/participants/add`	POST	Adiciona membros a um grupo	`participants`: Matriz de números
`/api/groups/send`	POST	Envia uma mensagem para um grupo	`groupId`: ID do grupo `message`: Conteúdo da mensagem

Integração com IA

Integração com Claude Desktop

Opção 1: Usando NPX

Inicie o servidor da API do WhatsApp:
```
npx wweb-mcp -m whatsapp-api -s local
```
Escaneie o código QR com o aplicativo móvel do WhatsApp

Anote a chave de API exibida nos logs:

WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

Adicione o seguinte à configuração do seu Claude Desktop:

{
    "mcpServers": {
        "whatsapp": {
            "command": "npx",
            "args": [
                "wweb-mcp",
                "-m", "mcp",
                "-s", "local",
                "-c", "api",
                "-t", "command",
                "--api-base-url", "http://localhost:3001/api",
                "--api-key", "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
            ]
        }
    }
}

Opção 2: Usando Docker

Inicie o servidor da API do WhatsApp no Docker:

docker run -i -p 3001:3001 -v wweb-mcp:/wwebjs_auth --rm wweb-mcp:latest -m whatsapp-api -s local -a /wwebjs_auth

Escaneie o código QR com o aplicativo móvel do WhatsApp

Anote a chave de API exibida nos logs:

WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

Adicione o seguinte à configuração do seu Claude Desktop:

{
    "mcpServers": {
        "whatsapp": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "wweb-mcp:latest",
                "-m", "mcp",
                "-s", "local",
                "-c", "api",
                "-t", "command",
                "--api-base-url", "http://host.docker.internal:3001/api",
                "--api-key", "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
            ]
        }
    }
}

Reinicie o Claude Desktop
A funcionalidade do WhatsApp estará disponível através da interface do Claude

Arquitetura

O projeto é estruturado com uma separação clara de responsabilidades:

Componentes

WhatsAppService: Lógica de negócios principal para interagir com o WhatsApp
WhatsAppApiClient: Cliente para conectar-se à API do WhatsApp
API Router: Rotas Express para a API REST
MCP Server: Implementação do Model Context Protocol

Opções de Implantação

Servidor da API do WhatsApp: Servidor REST API independente
Servidor MCP (Independente): Conexão direta com o WhatsApp Web
Servidor MCP (Cliente de API): Conexão com o servidor da API do WhatsApp

Esta arquitetura permite cenários flexíveis de implantação, incluindo:

Executar o servidor da API e o servidor MCP em máquinas diferentes
Usar o servidor MCP como cliente de um servidor de API existente
Executar tudo em uma única máquina para simplicidade

Desenvolvimento

Estrutura do Projeto

src/
├── whatsapp-client.ts     # WhatsApp Web client implementation
├── whatsapp-service.ts    # Core business logic
├── whatsapp-api-client.ts # Client for the WhatsApp API
├── api.ts                 # REST API router
├── mcp-server.ts          # MCP protocol implementation
└── main.ts                # Application entry point

Compilando a partir do Código Fonte

npm run build

Testes

O projeto usa Jest para testes unitários. Para executar os testes:

# Run all tests
npm test

# Run tests in watch mode during development
npm run test:watch

# Generate test coverage report
npm run test:coverage

Lint e Formatação

O projeto usa ESLint e Prettier para qualidade de código e formatação:

# Run linter
npm run lint

# Fix linting issues automatically
npm run lint:fix

# Format code with Prettier
npm run format

# Validate code (lint + test)
npm run validate

A configuração de lint impõe boas práticas de TypeScript e mantém um estilo de código consistente em todo o projeto.

Solução de Problemas

Problemas de Integração com Claude Desktop

Não é possível iniciar o wweb-mcp no modo independente de comando no Claude porque o Claude abre mais de um processo, várias vezes, e cada wweb-mcp precisa abrir uma sessão do puppeteer que não pode compartilhar a mesma autenticação do WhatsApp. Devido a essa limitação, dividimos o aplicativo em modos MCP e API para permitir a integração adequada com o Claude.

Recursos Futuros

Criar webhooks para mensagens recebidas e outros eventos do WhatsApp
Suporte para envio de arquivos de mídia (imagens, áudio, documentos)
Recursos de gerenciamento de grupos de chat
Gerenciamento de contatos (adicionar/remover contatos)
Modelos de mensagem para cenários comuns
Tratamento de erros e recuperação aprimorados

Contribuindo

Faça um fork do repositório
Crie um branch de funcionalidade
Faça commit das suas alterações
Envie para o seu branch
Crie um Pull Request

Certifique-se de que seu PR:

Segue o estilo de código existente
Inclui testes apropriados
Atualiza a documentação conforme necessário
Descreve as alterações em detalhes

Dependências

WhatsApp Web.js

Este projeto usa whatsapp-web.js, uma biblioteca cliente JavaScript não oficial para o WhatsApp Web que se conecta através do aplicativo de navegador do WhatsApp Web. Para mais informações, visite o repositório GitHub do whatsapp-web.js.

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.

Registro de Logs

O WhatsApp Web MCP inclui um sistema robusto de registro de logs construído com Winston. O sistema de registro fornece:

Múltiplos níveis de log (error, warn, info, http, debug)
Saída no console com logs coloridos
Registro de requisições/respostas HTTP para endpoints da API
Tratamento estruturado de erros
Níveis de log cientes do ambiente (desenvolvimento vs. produção)
Todos os logs direcionados ao stderr ao executar no modo de comando MCP

Níveis de Log

O aplicativo suporta os seguintes níveis de log, em ordem de verbosidade:

error - Erros críticos que impedem o funcionamento do aplicativo
warn - Avisos que não interrompem o aplicativo, mas exigem atenção
info - Informações gerais sobre o estado e eventos do aplicativo
http - Registro de requisições/respostas HTTP
debug - Informações detalhadas de depuração

Configurando o Nível de Log

Você pode configurar o nível de log ao iniciar o aplicativo usando o sinalizador --log-level ou -l:

npm start -- --log-level=debug

Ou ao usar a instalação global:

wweb-mcp --log-level=debug

Registro de Logs no Modo de Comando

Ao executar no modo de comando MCP (--mode mcp --transport command), todos os logs são direcionados ao stderr. Isso é importante para ferramentas de linha de comando onde o stdout pode ser usado para saída de dados enquanto o stderr é usado para logs e diagnósticos. Isso garante que a comunicação do protocolo MCP pelo stdout não seja interferida por mensagens de log.

Ambiente de Teste

Em ambientes de teste (quando NODE_ENV=test ou quando executando com Jest), o logger ajusta automaticamente seu comportamento para ser adequado a ambientes de teste.