A maioria dos tutoriais de WhatsApp MCP para no Claude Desktop. Este guia da Whapi.Cloud foi escrito para desenvolvedores que usam Cursor, VS Code e GitHub Copilot — com configurações JSON prontas para copiar e colar e uma etapa de verificação funcional para cada um.
A automação do WhatsApp antes exigia código personalizado — clientes REST, handlers de webhook, gerenciamento de sessão e lógica de atualização de token. O whapi-mcp substitui tudo isso com um comando em linguagem natural para o seu agente de IA. Instale o servidor MCP uma vez, cole uma configuração JSON e toda a biblioteca de ferramentas do WhatsApp estará disponível para qualquer cliente compatível com MCP que você já usa.
O que é MCP de Verdade
MCP — Model Context Protocol — é um sistema de plugins para agentes de IA chamarem ferramentas externas reais. Uma interface, muitos clientes compatíveis: execute um servidor MCP e cada agente conectado pode usar suas ferramentas sem integrações separadas por cliente.
Sem MCP, seu agente só pode sugerir ações. Com MCP, ele as executa — chama uma API, lê uma thread de mensagens, envia uma resposta, confirma a entrega. A diferença entre sugestão e automação é o acesso às ferramentas.
O que o whapi-mcp Oferece
whapi-mcp é um servidor MCP criado pela Whapi.Cloud que encapsula a API REST da Whapi e a expõe como ferramentas estruturadas para qualquer agente de IA compatível com MCP. Gerado automaticamente a partir da especificação OpenAPI da Whapi, as ferramentas cobrem mensagens, grupos, canais, contatos, mídia, etiquetas e mais — 165 no total.
Funciona no Cursor, VS Code Agent Mode, GitHub Copilot Chat, Windsurf e Claude Desktop. Todos os cinco clientes usam o mesmo pacote npm @whapi-cloud/whapi-mcp. Apenas o caminho do arquivo de configuração difere entre eles.
Ao contrário das bridges baseadas em QR, o whapi-mcp se conecta pela infraestrutura de produção da Whapi — sem arquivos de sessão locais, sem novos escaneamentos após quedas de rede, sem reconexões de madrugada. A estabilidade é gerenciada na nuvem, não na sua máquina de desenvolvimento.
| Recurso | whapi-mcp (Whapi.Cloud) | Bridge QR (sessão local) |
|---|---|---|
| Estabilidade de sessão | Estável em produção, gerenciado na nuvem | Cai em interrupções de rede; requer novo escaneamento QR |
| Tempo de configuração | Menos de 10 minutos (um comando npx) | 30 -- 60 min (servidor local + escaneamento QR + config de porta) |
| Suporte a múltiplos números | Sim -- múltiplos canais por conta | Tipicamente um número por instância de servidor |
| Cobertura de ferramentas MCP | 165 ferramentas estruturadas da especificação OpenAPI | Varia; frequentemente requer wrappers personalizados |
| API de Grupos e Canais | Acesso completo | Parcial ou instável |
Antes de Começar
Verifique estes pré-requisitos antes de executar qualquer comando de instalação:
-
Node.js 18 ou superior — necessário para executar
npx. Verifique comnode -vno terminal. -
Token de API da Whapi — registre-se em whapi.cloud, conecte um número de WhatsApp e copie o token nas configurações do canal no painel da Whapi.
-
IDE compatível com MCP — Cursor (qualquer versão recente), VS Code com Agent Mode habilitado, ou GitHub Copilot Chat no VS Code 1.99+ com um plano Copilot elegível.
Conecte o WhatsApp MCP em 10 Minutos
Cursor, VS Code e GitHub Copilot usam o mesmo pacote @whapi-cloud/whapi-mcp — apenas o caminho do arquivo de configuração difere. Instale o pacote uma vez via npx; configure uma vez por IDE.
Passo 1 — Execute o Servidor Uma Vez para Verificar
Antes de configurar qualquer IDE, execute isso no terminal para confirmar que o pacote resolve e o token é válido:
npx -y @whapi-cloud/whapi-mcp --api-token YOUR_WHAPI_TOKENSubstitua YOUR_WHAPI_TOKEN pelo seu token real. Se o servidor MCP iniciar sem erros — o token funciona. Não é necessária instalação global do npm; a configuração do IDE executa o npx automaticamente na inicialização.
Passo 2 — Configure seu IDE
Cada IDE lê a configuração do servidor MCP de um arquivo JSON específico. A estrutura interna é quase idêntica nos três clientes — apenas a chave externa e o local do arquivo diferem.
Cursor
Crie ou edite ~/.cursor/mcp.json para uma configuração global (aplica a todos os projetos), ou .cursor/mcp.json dentro da raiz do projeto para uma configuração de escopo de projeto:
{
"mcpServers": {
"whapi": {
"command": "npx",
"args": ["-y", "@whapi-cloud/whapi-mcp", "--api-token", "YOUR_WHAPI_TOKEN"]
}
}
}Salve, reinicie o Cursor e abra o painel do agente — as ferramentas whapi aparecem na lista de ferramentas disponíveis.
VS Code (Agent Mode)
Crie .vscode/mcp.json na raiz do workspace. O VS Code Agent Mode lê este arquivo automaticamente. Observe a chave "type": "stdio" — obrigatória pelo esquema de configuração MCP do VS Code:
{
"servers": {
"whapi": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@whapi-cloud/whapi-mcp", "--api-token", "YOUR_WHAPI_TOKEN"]
}
}
}Habilite o Agent Mode nas configurações do VS Code se ainda não estiver ativo. O servidor whapi iniciará quando você abrir o painel do agente.
GitHub Copilot (VS Code)
Para o GitHub Copilot Chat no VS Code, adicione a entrada MCP ao seu settings.json de nível de usuário, ou crie .github/copilot/mcp.json na raiz do projeto. O suporte a MCP requer VS Code 1.99+ e um plano Copilot elegível:
{
"mcpServers": {
"whapi": {
"command": "npx",
"args": ["-y", "@whapi-cloud/whapi-mcp", "--api-token", "YOUR_WHAPI_TOKEN"]
}
}
}Abra o Copilot Chat no modo Agent após salvar — as ferramentas whapi aparecem no seletor de ferramentas.
Claude Desktop
Se você também usa o Claude Desktop, a configuração vai no claude_desktop_config.json. A estrutura é idêntica à do Cursor:
{
"mcpServers": {
"whapi": {
"command": "npx",
"args": ["-y", "@whapi-cloud/whapi-mcp", "--api-token", "YOUR_WHAPI_TOKEN"]
}
}
}Passo 3 — Proteja seu Token
Nunca cole o token de API da Whapi em um arquivo de configuração que você envia para o controle de versão. Referencie uma variável de ambiente — a maioria dos clientes MCP suporta uma chave "env" na configuração do servidor:
{
"mcpServers": {
"whapi": {
"command": "npx",
"args": ["-y", "@whapi-cloud/whapi-mcp", "--api-token", "${WHAPI_TOKEN}"]
}
}
}Defina WHAPI_TOKEN no ambiente do sistema ou em um arquivo .env excluído do git. Adicione o arquivo de configuração ao .gitignore se ele contiver um token bruto. Exemplos completos estão no guia de configuração do Whapi MCP.
Verifique sua Conexão
Após reiniciar o IDE, abra seu agente de IA e execute:
List my WhatsApp chatsUma conexão funcional retorna seus chats recentes com seus Chat IDs. Se aparecerem — a configuração está concluída. Seu agente de IA agora tem acesso direto ao WhatsApp.
Erros do servidor MCP quase sempre rastreiam dois erros: caminho errado do arquivo de configuração ou vírgulas finais no JSON. Ambos causam falhas de parse silenciosas.
O que Você Pode Fazer — 6 Casos de Uso Reais
Conecte o MCP uma vez; seu agente de IA envia mensagens, gerencia grupos e lê chats via um prompt em linguagem natural. Seis operações que funcionam imediatamente após a configuração:
-
"Envie uma mensagem para João dizendo que o pedido dele está pronto" — o agente chama
sendMessageTextcom o Chat ID de João e o corpo da mensagem. -
"Crie um grupo do WhatsApp chamado Sprint Team e adicione esses 5 números" — chama
createGrouppara criar o grupo, depoisaddGroupParticipantcom o array de participantes. -
"Leia as últimas 20 mensagens do chat de suporte" — chama
getMessagescom o chat ID e a contagem. Retorna a thread completa. -
"Envie o invoice.pdf para o cliente no WhatsApp" — chama
sendMessageDocumentcom a referência do arquivo e o Chat ID do destinatário. -
"Liste todos os chats não lidos e resuma os tópicos" — chama
getChatspara a lista de chats, depoisgetMessagespor chat — a IA extrai e resume o contexto. -
"Publique uma atualização de produto no nosso canal do WhatsApp" — chama
sendMessageTextcom o Chat IDCHANNELID@newsletterdo canal como destinatário.
Cada prompt mapeia para uma chamada de ferramenta. O agente seleciona a ferramenta, preenche os parâmetros e retorna o resultado — sem código de integração para escrever ou manter.
Whapi Agent Skill — Elimine Erros de Formato
Agentes de IA alucinam Chat IDs do WhatsApp. Sem conhecimento explícito do formato, o modelo inventa identificadores estruturalmente incorretos — e a chamada de ferramenta falha mesmo quando o agente seleciona a ferramenta certa.
O WhatsApp usa três formatos distintos de Chat ID que devem ser usados exatamente:
-
[email protected]— contatos individuais (ex.:[email protected]) -
[email protected]— chats em grupo (ex.:[email protected]) -
CHANNELID@newsletter— Canais do WhatsApp (ex.:120363123456789012@newsletter)
O Whapi Agent Skill é um arquivo de conhecimento para download para Cursor e VS Code. Instale uma vez — o agente carrega as regras de formato de Chat ID e os padrões de uso no contexto antes de cada sessão. A taxa de sucesso na primeira tentativa melhora; a depuração de Chat ID cai a quase zero.
As instruções de instalação estão no guia do Whapi Agent Skills. Use o whapi-mcp e o Agent Skill juntos — eles foram feitos para isso.
Solução Rápida de Problemas
Três problemas que causam a maioria das configurações com falha:
-
Servidor MCP não encontrado após reiniciar o IDE — o arquivo de configuração está no caminho errado ou tem um erro de sintaxe JSON. A configuração global do Cursor fica em
~/.cursor/mcp.json. O VS Code lê.vscode/mcp.jsonda raiz do workspace. Valide seu JSON com um linter — vírgulas finais causam falhas de parse silenciosas. -
Erro de autenticação ou resposta 401 — o token de API é inválido, expirou ou foi colado com espaços extras. Copie-o novamente diretamente das configurações do canal no painel da Whapi e substitua o valor na sua configuração.
-
npx falha ao resolver o pacote — confirme que o Node.js 18+ está instalado (
node -v). Em redes corporativas ou VPN, verifique se o acesso ao registro npm não está bloqueado. Tentenpm install -g @whapi-cloud/whapi-mcpcomo alternativa e atualize o config para usar"command": "whapi-mcp".
Para casos de borda e padrões de configuração adicionais, consulte o guia de configuração do Whapi MCP. O código-fonte e os issues abertos estão no GitHub (Whapi-Cloud/whapi-mcp).
Obtenha seu token de API e execute seu primeiro comando de agente do WhatsApp em menos de 10 minutos. Se encontrar um caso de borda não coberto aqui, abra o chat de suporte nesta página — o time da Whapi responde rapidamente.
