WhatsApp no Claude: servidor MCP da ZapZap no Claude Code e no Claude Desktop

Passo a passo

1. 1

   Gere a chave e conecte um número

   No painel (app.zapzapapi.com), abra Settings > API e copie a API Key e o API Secret. Crie uma instância e conecte o número pelo QR code. Exporte as duas chaves no seu terminal como ZAPZAP_API_KEY e ZAPZAP_API_SECRET: elas vão para o ambiente do servidor, nunca para o prompt.

2. 2

   Clone e compile o servidor MCP

   Precisa de Node.js 18 ou mais. Rode git clone https://github.com/zapzapapi/zapzap-mcp.git e, dentro da pasta, npm install e npm run build. O README do repositório prevê npx -y zapzap-mcp, mas em 11/11/2026 o pacote ainda não está publicado no npm (o registro responde 404). Por isso o caminho que funciona hoje é clonar, compilar e apontar o comando para dist/src/index.js.

3. 3

   Registre no Claude Code

   Use claude mcp add com as variáveis de ambiente e o separador -- antes do comando, como na documentação do Claude Code (lida em 11/11/2026): claude mcp add --env ZAPZAP_API_KEY=... --env ZAPZAP_API_SECRET=... --transport stdio zapzap -- node /caminho/zapzap-mcp/dist/src/index.js. O escopo padrão é local (só você, neste projeto); -s project grava no .mcp.json do repositório, que vai para o controle de versão, então nunca coloque a chave nele. Confirme com claude mcp list e, dentro do Claude Code, com /mcp.

4. 4

   Ou registre no Claude Desktop

   Em Settings > Developer > Edit Config, edite o claude_desktop_config.json (macOS: ~/Library/Application Support/Claude; Windows: %APPDATA%\Claude) e adicione mcpServers.zapzap com command node, args apontando para o dist/src/index.js (caminho absoluto) e env com as duas chaves. Saia do Claude Desktop por completo e abra de novo, como manda o guia do MCP (lido em 11/11/2026).

5. 5

   Teste só com leitura

   Peça: "liste minhas instâncias e diga qual está conectada" e depois "cheque se 5511999999999 tem WhatsApp". São ferramentas de leitura (list_instances, get_instance_status, check_whatsapp_numbers). Só depois remova ZAPZAP_READ_ONLY para liberar o envio.

6. 6

   Libere o envio com aprovação a cada chamada

   As ferramentas de envio são marcadas como não idempotentes e destrutivas, então o cliente MCP pede confirmação antes de cada send_text. Mantenha essa confirmação ligada, use uma instância dedicada e nunca deixe o assistente enviar para uma lista que você não revisou.

# 1) Build the MCP server from the repository (the npm package is not published yet)
git clone https://github.com/zapzapapi/zapzap-mcp.git
cd zapzap-mcp && npm install && npm run build

# 2) Register it in Claude Code (keys come from your shell, never from the prompt)
claude mcp add --env ZAPZAP_API_KEY="$ZAPZAP_API_KEY" --env ZAPZAP_API_SECRET="$ZAPZAP_API_SECRET" --env ZAPZAP_READ_ONLY=true --transport stdio zapzap -- node "$PWD/dist/src/index.js"

# 3) Check that it connected
claude mcp list