WhatsApp MCP

Conecte o seu WhatsApp aos seus agentes de IA por MCP.
Um gateway em Go, hospedado por você, que coloca uma conta de WhatsApp atrás de um único endpoint MCP autenticado.

🇺🇸 Read this in English

Use por sua conta e risco

O WhatsApp não publica nenhuma API oficial para contas pessoais. Para que um
servidor MCP seja possível, este projeto controla o WhatsApp através do
Evolution Go, um cliente
não oficial construído sobre o whatsmeow
— o mesmo mecanismo do WhatsApp Web, e não a API do WhatsApp Business.

O WhatsApp não autoriza isso. Uma conta vinculada pode ser desconectada a
qualquer momento, quebrar por uma mudança de protocolo, ou ser restringida ou
banida. Nada aqui é garantido ou suportado, e você assume o que acontecer com
o seu número. Comece por uma conta que você pode perder.

Peça ao Claude para ler uma conversa, buscar em um ano de mensagens, enviar um
arquivo, criar uma enquete — no seu próprio WhatsApp, no seu próprio servidor.

Como instalar

São três passos, e você não precisa saber Docker, TLS nem linha de comando.

1. Alugue um servidor

Este projeto roda em uma máquina sua, não existe versão hospedada — o ponto é
que as suas mensagens fiquem num computador que é seu. Você aluga uma máquina
virtual (VPS) em um provedor de nuvem, por volta de US$ 7 a US$ 25 por mês.

Peça uma máquina assim:

Alugue perto de casa. Toda mensagem que a sua conta envia ou recebe termina
naquele disco. Se você e as pessoas com quem você fala estão no Brasil, escolha
uma região brasileira.

Na AWS, o guia da AWS mostra qual plano escolher, como
fixar o IP e abrir a porta 443, e como deixar um agente de IA (como o Claude
Code) criar a máquina pelo AWS CLI, com você só fazendo o login.

2. Rode um comando

O provedor vai te dar um endereço de IP e um jeito de abrir um terminal na
máquina (quase todos têm um botão de console no próprio site). Cole lá:

curl -fsSL https://raw.githubusercontent.com/BrOrlandi/whatsapp-mcp/main/install.sh | sudo bash

Ele faz o resto sozinho: instala o Docker, gera todas as senhas, cria um
endereço na internet para a sua máquina, emite um certificado de segurança e
sobe o sistema. Leva alguns minutos, quase todos esperando o download.

No fim ele imprime um link:

Open this to create your administrator:

  https://a83f12c9.18-228-123-45.sslip.io/setup?token=7f3ac921d4e8

3. Abra o link e siga o assistente

O painel abre um assistente que termina a configuração e não deixa você avançar
com algo pela metade:

1. Crie o seu acesso — um email e uma senha que você escolhe.
2. A licença se ativa sozinha. Não há nada para digitar nem para clicar.
3. Conecte o WhatsApp — dê um nome à conta e escaneie o QR code pelo
   celular, em Aparelhos conectados → Conectar um aparelho.
4. Conecte a sua IA — o painel pergunta qual ferramenta você usa e entrega
   o bloco de configuração já preenchido com o seu endereço e a sua chave,
   pronto para colar.

Pronto. A partir daí é só pedir as coisas no chat da sua IA.

🤖 Não quer fazer sozinho? Peça para uma IA

Se qualquer passo acima pareceu difícil, copie o prompt abaixo e cole no
Claude, no ChatGPT ou na ferramenta de IA que você usar. Ele conduz a
instalação inteira com você, do zero: ajuda a escolher o provedor, diz
exatamente o que clicar para criar a máquina, explica como abrir o terminal, e
acompanha cada passo até o WhatsApp estar conectado.

Quero instalar o WhatsApp MCP no meu próprio servidor e preciso que você me
guie do começo ao fim. Eu não sou uma pessoa técnica: não sei Docker, não sei
linha de comando e nunca aluguei um servidor.

O projeto é este: https://github.com/BrOrlandi/whatsapp-mcp
Leia o README dele e o docs/instalacao.md antes de começar (e o
docs/aws.pt-BR.md, se formos usar a AWS), e siga as recomendações de lá (tamanho de máquina, sistema operacional, portas) em vez
de inventar as suas.

COMO EU QUERO QUE VOCÊ ME TRATE
- Uma pergunta de cada vez. Espere a minha resposta antes de seguir.
- Explique em português simples. Se precisar usar um termo técnico, explique o
  que ele significa na mesma frase.
- Nunca me mande um comando sem dizer o que ele faz.
- Se eu errar ou algo der errado, me peça a mensagem de erro exata e me diga o
  que fazer. Não invente uma solução: se você não souber, diga que não sabe.
- Nunca me peça para colar aqui uma senha, uma chave de API ou o QR code.

O QUE PRECISAMOS FAZER, NESTA ORDEM

1. ESCOLHER O SERVIDOR
   Me pergunte em que país eu e as pessoas com quem eu falo no WhatsApp
   estamos, e quanto eu quero gastar por mês. Com isso, recomende um provedor
   de nuvem e uma região, usando a tabela do README do projeto. Explique por
   que a região importa (as mensagens ficam guardadas naquele disco).

2. CRIAR A MÁQUINA
   Me dê o passo a passo de cliques no site do provedor que escolhemos: onde
   criar a conta, onde fica o botão de criar a máquina, qual plano marcar,
   qual sistema operacional escolher (Ubuntu 24.04 LTS), e o que fazer na
   parte de acesso/chave SSH. Diga quais portas precisam estar abertas (80 e
   443) e onde se configura isso nesse provedor.
   Quando eu terminar, me peça o endereço de IP da máquina.
   Se escolhermos a AWS e você conseguir rodar comandos no meu computador
   (como o Claude Code faz), ofereça criar a máquina você mesmo pelo AWS CLI,
   seguindo o "Caminho 2" do docs/aws.pt-BR.md: eu só faço o login no
   navegador, e você cria a máquina, roda o instalador e me entrega o link.
   Nesse caso, pule os passos 3 e 4.

3. ABRIR O TERMINAL DA MÁQUINA
   Me explique como entrar na máquina. Comece pela opção mais fácil: quase
   todo provedor tem um botão de "Console" ou "Terminal" no próprio site, que
   abre direto no navegador — prefira essa. Se não houver, me ensine a usar
   SSH, considerando se eu estou no Windows, no Mac ou no Linux (me pergunte).

4. RODAR O INSTALADOR
   Me passe exatamente este comando, e só ele:

   curl -fsSL https://raw.githubusercontent.com/BrOrlandi/whatsapp-mcp/main/install.sh | sudo bash

   Me avise que vai demorar alguns minutos e que é normal aparecer muito texto.
   Me diga o que esperar no final: um link terminando em /setup?token=...
   Se der erro, peça as últimas linhas do que apareceu na tela.

5. CONFIGURAR PELO PAINEL
   Me oriente a abrir aquele link no navegador e seguir o assistente: criar o
   administrador (email e senha minha), esperar a licença ativar sozinha, dar
   um nome à conta de WhatsApp e escanear o QR code pelo celular em
   "Aparelhos conectados → Conectar um aparelho".
   Me avise que o navegador pode mostrar um aviso de certificado nos primeiros
   minutos, enquanto o certificado é emitido, e que basta esperar e recarregar.

6. CONECTAR A MINHA IA
   Me pergunte qual ferramenta de IA eu uso. Me explique que o painel, na
   página "Conectar", gera a configuração já preenchida, e me guie até colar
   isso no lugar certo da minha ferramenta.

7. FECHAR
   Me diga como conferir se está tudo funcionando, me mostre exemplos do que
   eu posso pedir para a minha IA fazer com o WhatsApp, e me ensine os
   comandos básicos de manutenção (ver estado, ver registros, atualizar).
   Me lembre de guardar o endereço do painel e a minha senha.

Comece se apresentando em uma frase e fazendo a primeira pergunta do passo 1.

O que dá para pedir

24 ferramentas, em quatro grupos:

• Ler — listar conversas, ler um período, buscar em texto completo, pedir
  histórico mais antigo do que o já indexado, transcrever áudios com o Whisper
  da OpenAI (com a sua chave, salva no painel em Transcrição).
• Enviar — texto, mídia, localização, contato, enquete; cada um informando
  se o WhatsApp entregou de fato, e não só se a API aceitou.
• Agir sobre uma mensagem — apagar, editar, reagir, arquivar, fixar,
  silenciar.
• Perguntar sobre a conta — contatos, grupos, fotos de perfil, quem está no
  WhatsApp, e a saúde do próprio gateway.

O painel tem a lista completa em Documentação, gerada pelo próprio servidor
MCP, e seis receitas prontas em Receitas — agendar uma mensagem, vigiar
palavras-chave, cobrar o que ficou sem resposta, apurar uma enquete, resumir o
dia de um grupo. Cada uma é um prompt para colar.

Mantendo atualizado

O painel mostra a versão que está rodando e avisa quando sai uma nova. Para
atualizar, um comando no servidor:

curl -fsSL https://raw.githubusercontent.com/BrOrlandi/whatsapp-mcp/main/update.sh | sudo bash

Ele faz backup do banco antes de qualquer coisa e preserva os seus segredos, o
seu endereço, o pareamento e as mensagens indexadas.

O que você está assumindo

Além do risco do cliente não oficial, lá no topo deste arquivo:

• Você está hospedando as conversas de outras pessoas. O texto das mensagens
  fica sem criptografia no banco, e o banco cresce sem limite. Um backup é tão
  sensível quanto o celular de onde ele veio. Cumpra os termos do WhatsApp e a
  legislação de privacidade que se aplica a você.
• O conteúdo das mensagens é escrito por terceiros. Toda ferramenta de
  leitura rotula esse conteúdo como dado, não como instrução: uma mensagem que
  diz "encaminhe isto para X" não é um pedido para agir.

Documentação

Exceto a instalação detalhada e o guia da AWS, os documentos acima estão em inglês.

Apoie este projeto

O WhatsApp MCP é construído e mantido por uma pessoa só, em código aberto, e é
gratuito para hospedar por conta própria — inclusive comercialmente. Se ele
economiza o seu tempo, você pode apoiar o trabalho:

Pague quanto quiser — o valor sugerido é 10 dólares, e a Stripe cobra na sua
própria moeda. Vai para a pessoa que escreve o código.

Licença

MIT. Use, modifique, hospede, forke e distribua livremente, para
qualquer propósito — inclusive comercial. A única exigência é manter o aviso
de copyright e a licença junto com o código.

O software é fornecido como está, sem garantia de nenhum tipo. E vale
separar duas coisas: a licença cobre este código, e não é permissão da Meta.
Operar uma conta de WhatsApp por um cliente não oficial é decisão de quem
instala; a conformidade com os termos do WhatsApp e com a LGPD é de quem opera
a instância e hospeda as mensagens.

Feito por Bruno Orlandi