WhatsApp Claude Plugin

Canal WhatsApp para Claude Code

Conduza sua sessão do Claude Code pelo WhatsApp — seu número pessoal, sem bots, sem chaves de API.

O plugin conecta-se ao WhatsApp como um dispositivo vinculado (o mesmo protocolo do WhatsApp Web, via Baileys) e o expõe ao Claude Code como um canal MCP. Mensagens recebidas chegam à sua sessão em tempo real; Claude responde do seu próprio número, então os destinatários veem um chat normal. Tudo roda localmente na sua máquina — as mensagens trafegam diretamente entre o WhatsApp e sua sessão, sem servidores de terceiros no meio. Uma vez pareado, continua funcionando enquanto seu telefone estiver desligado; apenas a sessão do Claude Code precisa permanecer aberta, e reconexões nunca exigem re-pareamento.

Publicado no Mercado Oficial de Plugins da Anthropic — o primeiro plugin de canal WhatsApp construído pela comunidade, revisado e publicado pela Anthropic.

Instalação

claude plugin marketplace add Rich627/whatsapp-claude-plugin
claude plugin install whatsapp-channel@whatsapp-claude-plugin
claude --dangerously-load-development-channels plugin:whatsapp-channel@whatsapp-claude-plugin

A flag --dangerously-load-development-channels é importante: ela registra o plugin como um canal, então uma mensagem recebida no WhatsApp desperta sua sessão imediatamente. Sem ela, as ferramentas ainda carregam, mas nada desperta a sessão quando mensagens chegam — elas ficam sem resposta até você (ou um watchdog) solicitar que Claude verifique. --channels ainda não aceita este plugin (não está na lista de permissões da prévia de pesquisa), então a flag de desenvolvimento é atualmente a única forma.

Dentro da sessão, defina seu número e pareie:

/whatsapp-channel:configure <phone>   # country code + number, no +

Um código de pareamento é exibido no primeiro lançamento. No seu telefone: WhatsApp → Configurações → Dispositivos vinculados → Vincular um dispositivo → Vincular com número de telefone → insira o código. Não envolve WhatsApp Business API, conta de desenvolvedor Meta ou chave de API — ele vincula à sua conta regular.

Outros clientes MCP (Codex CLI, Gemini CLI, Cursor)

O servidor é um servidor MCP stdio simples, então qualquer cliente MCP pode executá-lo. Duas coisas são específicas do Claude Code e vale a pena saber antes de começar:

• Mensagens recebidas não são enviadas por push. Despertar uma sessão em uma mensagem recebida usa notifications/claude/channel, uma extensão do Claude Code. O MCP não tem equivalente padrão que alcance o modelo, e outros clientes descartam notificações desconhecidas silenciosamente. Em outros lugares, o plugin é baseado em polling: chame wait_for_messages (aguarda até 40s pela próxima mensagem) ou catch_up / unreplied. Cada resultado de ferramenta também carrega uma contagem de mensagens sem resposta, então um cliente descobre que há tráfego na próxima chamada, seja qual for essa chamada.
• A configuração é feita a partir de um terminal, não de um comando de barra. /whatsapp-channel:access e amigos são habilidades do Claude Code. Use bun scripts/access.ts em vez disso (veja Controle de acesso a partir de um terminal).

Registre o servidor com um caminho absoluto — ${CLAUDE_PLUGIN_ROOT} é substituído apenas pelo Claude Code:

Codex CLI (~/.codex/config.toml)

[mcp_servers.whatsapp]
command = "bun"
args = ["run", "--cwd", "/absolute/path/to/whatsapp-channel", "start"]
startup_timeout_sec = 30   # default 10 is tight for a first Baileys connect
tool_timeout_sec = 120     # default 60; wait_for_messages parks for up to 40s

Gemini CLI (~/.gemini/settings.json)

{
  "mcpServers": {
    "whatsapp": {
      "command": "bun",
      "args": ["run", "--cwd", "/absolute/path/to/whatsapp-channel", "start"],
      "timeout": 600000
    }
  }
}

Cursor (~/.cursor/mcp.json para todos os projetos, .cursor/mcp.json para um)

{
  "mcpServers": {
    "whatsapp": {
      "type": "stdio",
      "command": "bun",
      "args": ["run", "--cwd", "/absolute/path/to/whatsapp-channel", "start"]
    }
  }
}

Apenas um cliente por vez pode manter a conexão WhatsApp: o WhatsApp permite uma sessão de dispositivo vinculado por conta, e dois servidores se expulsariam mutuamente. Um segundo servidor não falha silenciosamente — ele permanece ativo e serve uma única ferramenta whatsapp_unavailable nomeando o processo que mantém a conexão.

Controle de acesso a partir de um terminal

Tudo o que a habilidade de acesso faz, sem o Claude Code:

bun scripts/access.ts status                 # policy, allowlist, pending codes, groups
bun scripts/access.ts policy pairing         # open the door
bun scripts/access.ts pair <code>            # approve someone who messaged you
bun scripts/access.ts allow <jid>            # add directly
bun scripts/access.ts remove <jid>
bun scripts/access.ts group add <groupJid> [--mention] [--allow jid1,jid2]
bun scripts/access.ts set replyToMode first  # ackReaction, textChunkLimit, chunkMode, mentionPatterns

Aprovar sempre exige o código específico, mesmo quando apenas um pareamento está pendente: qualquer pessoa pode criar uma entrada pendente apenas enviando mensagem para a conta, então "aprovar o pendente" é exatamente o que uma solicitação injetada por prompt parece. Pela mesma razão, este é um comando de terminal e deliberadamente não é uma ferramenta MCP, para que nada que chegue pelo WhatsApp possa alcançá-lo.

Recursos

• Mensagens bidirecionais. Envie e receba da sessão; respostas longas são divididas nos limites do WhatsApp ou enviadas como anexo de documento além de um limite configurável.
• Menções com @. reply pode marcar pessoas para que elas realmente sejam notificadas — ids são aceitos como telefone, LID ou JID completo, e as menções são anexadas apenas ao trecho que as nomeia.
• Suporte completo a mídia. Fotos, notas de voz, vídeo, documentos e figurinhas, em ambas as direções.
• Transcrição de voz. Notas de voz recebidas são transcritas localmente via mlx-whisper (veja configuração); sem o script, elas chegam como anexos simples.
• Controle de acesso. Códigos de pareamento, listas de permissões e políticas por grupo controlam cada mensagem recebida — estranhos nunca alcançam sua sessão. Gerenciado via /whatsapp-channel:access no Claude Code, ou bun scripts/access.ts em qualquer lugar.
• Personalidades por grupo. Cada grupo tem seu próprio config.md com personalidade personalizada e memória de conversa.
• Retransmissão de permissões. Aprove ou negue solicitações de ferramentas do Claude pelo WhatsApp com uma reação de emoji (👍 / 👎).
• Tarefas agendadas. Uma seção ## Cron Jobs no config.md de um grupo agenda tarefas recorrentes no servidor.
• Recuperação de contexto. Após uma reinicialização, a ferramenta catch_up reproduz conversas bidirecionais recentes por chat, contagens sem resposta e tarefas abertas de tasks.md, para que uma nova sessão retome o trabalho em andamento.
• Contas duplas. Execute números pessoais e comerciais lado a lado com estados e comportamentos separados.
• Autodiagnóstico. /whatsapp-channel:doctor verifica o processo do servidor, o vínculo do dispositivo, o bloqueio de instância única e a configuração, e então orienta você nas correções — sem mais adivinhações sobre por que as respostas pararam.

Como funciona

WhatsApp (phone) <──Baileys──> MCP Server <──stdio──> Claude Code

O servidor (um único processo Bun) mantém a conexão do dispositivo vinculado e encaminha mensagens recebidas para a sessão como notificações de canal após passarem pelo portão de acesso. Claude age por meio de ferramentas MCP — reply, react, edit_message, download_attachment, status, unreplied, catch_up, list_groups. O estado de execução (autenticação, listas de permissões, configurações de grupo, caixa de entrada) vive em ~/.whatsapp-channel/, nunca no repositório.

Mensagens enviadas por Claude aparecem como vindas do seu número de telefone. Use um número dedicado se quiser uma identidade de bot distinta.

Transcrição de voz (opcional)

Configuração única (Apple Silicon, mlx-whisper):

brew install ffmpeg                      # mlx-whisper uses it to decode audio
python3 -m venv ~/whisper-env
source ~/whisper-env/bin/activate
pip install mlx-whisper
cp scripts/whisper-transcribe.sh ~/whisper-transcribe.sh
chmod +x ~/whisper-transcribe.sh
~/whisper-transcribe.sh path/to/sample.ogg   # optional: test

O script de referência usa mlx-community/whisper-large-v3-turbo — preciso, rápido, multilíngue. Troque o modelo no script se preferir um menor.

Solução de problemas

Problema	Solução
Código de pareamento não aparece	Execute /whatsapp-channel:configure <phone> primeiro e reinicie
Erro de desconexão 440	Apenas uma conexão por estado de autenticação é permitida. Encerre processos obsoletos: pkill -f "whatsapp.*server"
Sessão não desperta com novas mensagens	Causa mais comum: iniciada sem --dangerously-load-development-channels plugin:whatsapp-channel@whatsapp-claude-plugin. As ferramentas funcionam, mas os pushes recebidos são descartados (Channel notifications skipped no log de depuração do MCP) — reinicie com a flag.
Mensagens não chegam	Bug conhecido do cliente Claude Code (#37933). O lado do servidor está correto, aguardando correção do cliente.
Respostas ainda enviam, nada chega	Envie um DM para o número conectado além de uma mensagem de grupo — um DM que chega enquanto grupos ficam silenciosos significa o caminho da chave do remetente do grupo, não a conexão. ~/.whatsapp-channel/diag.log registra uma linha inbound upsert para cada lote que o WhatsApp entrega, então distingue "nunca chegou" de "chegou e foi descartado". Defina WHATSAPP_DIAG_DEBUG=1 para o fluxo completo de depuração do Baileys.
Autenticação expirada	Execute /whatsapp-channel:configure reset-auth e re-pareie

Documentação

A documentação completa está em USAGE.md: controle de acesso, as ferramentas expostas ao assistente, configuração de contas duplas, conflitos de sessão e redefinição de autenticação.

Contribuindo

Issues e pull requests são bem-vindos — leia CONTRIBUTING.md antes de abrir um. Relate problemas de segurança de forma privada conforme SECURITY.md.

Histórico de Estrelas

Licença

Apache 2.0 — Copyright 2025 Richie Liu