Servidor MCP de WhatsApp na API Cloud oficial

Em resumo: o ZapClaw publica um servidor MCP para que os agentes de IA que a sua empresa cria possam ler e enviar mensagens de WhatsApp no seu próprio número. Ele roda na API Cloud oficial da Meta, cada envio passa pelas mesmas proteções da API REST e o número continua funcionando no app WhatsApp Business do seu celular.

Beta: o servidor MCP e as chaves de agente de IA estão em fase beta e ainda não estão liberados para todas as contas. A liberação será gradual, em breve.

Crie a chave do seu agente de IA no painel e depois adicione o servidor ao cliente em que o seu agente roda.

Criar conta Ver os passos de instalação

O que os seus agentes podem fazer

São os seus próprios agentes, trabalhando para os seus próprios clientes no seu próprio número.

O seu número continua funcionando no app

O ZapClaw conecta o número pela Coexistência do WhatsApp, então a sua equipe continua atendendo no app WhatsApp Business enquanto os seus agentes usam o mesmo número pela API oficial. Quando alguém da equipe responde pelo app, uma chave autônoma para de enviar a esse contato por 24 horas por padrão, para o agente não falar por cima de uma pessoa.

O que é preciso para conectar um número.

Instale no seu cliente

Primeiro crie uma chave de agente de IA (veja Criar uma chave de agente de IA). O pacote é @zapclaw/whatsapp-mcp, o endpoint remoto é https://mcp.zapclaw.app/mcp e o nome no registro é app.zapclaw/whatsapp. Não deixe a chave em arquivos compartilhados: use uma variável de ambiente, um arquivo de chave ou um prompt, como nos blocos abaixo.

Claude Code (stdio)

claude mcp add zapclaw --env ZAPCLAW_API_KEY_FILE=/path/to/zapclaw.key -- npx -y @zapclaw/whatsapp-mcp@1

Para um projeto que você compartilha, use o .mcp.json com uma expansão, assim a chave nunca vai parar no repositório.

{
  "mcpServers": {
    "zapclaw": {
      "command": "npx",
      "args": [
        "-y",
        "@zapclaw/whatsapp-mcp@1"
      ],
      "env": {
        "ZAPCLAW_API_KEY": "${ZAPCLAW_API_KEY}"
      }
    }
  }
}

No Windows nativo, o comando é cmd e os argumentos são ["/c", "npx", "-y", "@zapclaw/whatsapp-mcp@1"].

Claude Code (remote)

claude mcp add --transport http zapclaw https://mcp.zapclaw.app/mcp --header "X-API-Key: ${ZAPCLAW_API_KEY}"

Claude Desktop

Baixe o zapclaw-whatsapp.mcpb nos releases do GitHub e abra o arquivo. O Claude Desktop pede a chave como um campo sensível e a guarda. A alternativa é a configuração em JSON:

{
  "mcpServers": {
    "zapclaw": {
      "command": "npx",
      "args": [
        "-y",
        "@zapclaw/whatsapp-mcp@1"
      ],
      "env": {
        "ZAPCLAW_API_KEY": "${ZAPCLAW_API_KEY}"
      }
    }
  }
}

Cursor

No ~/.cursor/mcp.json, o servidor local:

{
  "mcpServers": {
    "zapclaw": {
      "command": "npx",
      "args": [
        "-y",
        "@zapclaw/whatsapp-mcp@1"
      ],
      "env": {
        "ZAPCLAW_API_KEY": "${env:ZAPCLAW_API_KEY}"
      }
    }
  }
}

Ou, no .cursor/mcp.json, o remoto:

{
  "mcpServers": {
    "zapclaw": {
      "url": "https://mcp.zapclaw.app/mcp",
      "headers": {
        "X-API-Key": "${env:ZAPCLAW_API_KEY}"
      }
    }
  }
}

VS Code

No .vscode/mcp.json, com um prompt de senha em vez de uma chave guardada:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "zapclaw-key",
      "description": "ZapClaw AI agent key",
      "password": true
    }
  ],
  "servers": {
    "zapclaw": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@zapclaw/whatsapp-mcp@1"
      ],
      "env": {
        "ZAPCLAW_API_KEY": "${input:zapclaw-key}"
      }
    }
  }
}

Codex

No ~/.codex/config.toml:

[mcp_servers.zapclaw]
command = "npx"
args = ["-y", "@zapclaw/whatsapp-mcp@1"]

[mcp_servers.zapclaw.env]
ZAPCLAW_API_KEY_FILE = "/path/to/zapclaw.key"

n8n

Use o nó MCP Client Tool com estas configurações:

A mensagem do contato já chega ao seu fluxo pelo webhook do ZapClaw, então o agente pode responder sem as ferramentas de conversa. O fluxo do n8n, pronto para importar.

OpenAI Responses API

{
  "type": "mcp",
  "server_label": "zapclaw",
  "server_url": "https://mcp.zapclaw.app/mcp",
  "authorization": "<agent key>",
  "require_approval": "always"
}

A chave viaja a cada requisição pela OpenAI, então use uma chave limitada aos números e às permissões de que o agente precisa.

Fixe a versão

Todos os blocos acima seguem a versão principal, @zapclaw/whatsapp-mcp@1. Se você não quer atualizações automáticas, use a forma exata, @zapclaw/whatsapp-mcp@1.0.0.

Entrar com OAuth (claude.ai, ChatGPT e outros)

Os clientes que fazem o login por você, em vez de guardar uma chave, se conectam ao mesmo endereço, https://mcp.zapclaw.app/mcp. Você entra no ZapClaw, aprova a conexão, escolhe os números e as permissões que ela recebe e pode revogá-la a qualquer momento em Aplicativos conectados, no painel. Nenhuma chave é copiada para lugar nenhum.

Um token de acesso é emitido para um único recurso, https://mcp.zapclaw.app/mcp, e é recusado em qualquer outro lugar. Uma conexão dura no máximo 90 dias; depois disso você entra de novo.

Um cliente que se registra sozinho só pode usar endereços de retorno que sejam URLs https, ou URLs http em localhost ou 127.0.0.1 para apps que rodam no seu computador. Qualquer outro endereço é recusado, então o login só pode voltar para o app que você aprovou.

As onze ferramentas

Cada ferramenta exige uma permissão na chave: ler os dados da conta, ler conversas ou enviar mensagens.

Ferramenta O que faz Permissão
zapclaw_whoamiMostra a qual conta a chave se conecta, com o modo e as permissões.account:read
whatsapp_list_numbersLista os números de WhatsApp que a chave pode usar.account:read
whatsapp_list_templatesLista os templates aprovados, com o limite de tamanho de cada variável.account:read
whatsapp_check_contactConfere um contato antes de enviar: se a janela de 24 horas está aberta e se o contato parou de receber mensagens de marketing.account:read
whatsapp_list_conversationsLista as conversas recentes.conversations:read
whatsapp_read_conversationLê uma conversa.conversations:read
whatsapp_send_textEnvia uma mensagem de texto dentro da janela de 24 horas.messages:send
whatsapp_send_templateEnvia um template aprovado, também fora da janela.messages:send
whatsapp_send_mediaEnvia uma imagem, um documento ou outro arquivo por link https, dentro da janela.messages:send
whatsapp_mark_readMarca uma mensagem recebida como lida.messages:send
whatsapp_get_send_statusConfere se um envio foi entregue, lido ou falhou.account:read

Feito para um agente não queimar o seu número

As regras abaixo rodam no servidor do ZapClaw em cada envio, venha de que cliente vier, até de um simples curl. Um cliente também pode pedir a uma pessoa que confirme cada envio, mas nada depende disso.

Como funcionam as aprovações

Quando uma regra pede uma pessoa, a mensagem não é enviada. A ferramenta responde que o envio está retido e entrega um link de aprovação e um código curto. Abra a página de aprovação no painel, leia a mensagem inteira, o destinatário, o número e os motivos, e escolha Aprovar e enviar ou Rejeitar.

Página de aprovação de um envio retido, com o código, o número de envio, o destinatário, os motivos, a mensagem completa e os botões Aprovar e enviar e Rejeitar Página de aprovação de um envio retido, com o código, o número de envio, o destinatário, os motivos, a mensagem completa e os botões Aprovar e enviar e Rejeitar

Criar uma chave de agente de IA

  1. No painel, abra Chaves de API e escolha Criar chave de agente de IA.
  2. Dê um nome à chave e escolha o modo: Assistente para um assistente de IA como Claude, ChatGPT, Cursor ou Codex, com uma pessoa acompanhando, ou Autônomo para uma automação como o n8n, que roda sem ninguém olhando.
  3. Escolha o que a chave pode fazer (ler os dados da conta, ler conversas, enviar mensagens) e quais números ela pode usar. As chaves autônomas começam sem leitura de conversas.
  4. Copie a chave, que aparece uma única vez, para uma variável de ambiente ou um arquivo de chave.

A proteção vale para os envios feitos pelo ZapClaw; um agente que pode ler conversas e também navegar na web ou executar comandos pode levar o que leu para outro lugar, então dê leitura só aos agentes que precisam.

Perguntas

Qual é a diferença para o servidor MCP de WhatsApp da própria Meta?

O servidor da Meta está em beta, exige acesso de administrador ao seu app da Meta e, segundo a própria Meta, serve para desenvolvimento e testes. O do ZapClaw é feito para os agentes que você roda em produção: proteções em cada envio, aprovação no painel e o número mantido no app WhatsApp Business.

E os servidores MCP de WhatsApp não oficiais?

Esses servidores controlam o WhatsApp Web, o que vai contra os termos do WhatsApp e coloca o número em risco de banimento. O ZapClaw usa a API Cloud oficial da Meta.

O servidor MCP tem preço próprio?

Não. Os envios são cobrados como qualquer outro envio pela API, e a Meta cobra as tarifas das mensagens de WhatsApp diretamente de você. Todos os planos e preços.

Quais planos incluem o servidor?

Todos, quando a liberação chegar à sua conta: o servidor está em fase beta e vai sendo liberado para as contas aos poucos. As mensagens enviadas por um agente contam na franquia de mensagens do seu plano, como qualquer envio pela API.

Posso oferecer um assistente de IA de uso geral ao público com ele?

Não. O servidor é para os agentes que uma empresa cria para os seus próprios clientes. Desde 15 de janeiro de 2026, a Meta permite que provedores de assistentes de IA de uso geral os ofereçam no WhatsApp apenas onde a Meta é obrigada por lei a permitir, e as demais empresas mantêm a precificação atual.

Conecte os seus agentes ao seu número de WhatsApp

Conecte o seu número, crie uma chave de agente de IA e adicione o servidor ao seu cliente.

Criar conta Ler a documentação (em inglês)