Servidor MCP de WhatsApp: como montar e usar no Claude e no Cursor

MCP (Model Context Protocol) é um protocolo aberto que define como um cliente de IA (um app de chat, um editor de código, um agente) descobre e chama ferramentas expostas por um servidor. Em vez de cada integração ser feita sob medida, o servidor declara as ferramentas, os parâmetros e as descrições, e o cliente decide quando chamá-las durante a conversa.

Para o WhatsApp isso abre usos concretos: pedir ao assistente que confirme se uma lista de números tem WhatsApp, que resuma as últimas mensagens de um cliente, que verifique se a instância está conectada antes de uma campanha ou que redija e, com a sua aprovação, envie uma mensagem. A parte difícil não é técnica, é de controle: um assistente com acesso de envio precisa de travas.

Estado em 27/10/2026. Existe: a API REST do ZapZap, com referência por endpoint e arquivo OpenAPI publicado em OpenAPI; o pacote n8n-nodes-zapzap 0.1.3 no npm, para quem usa n8n; e a SDK oficial do MCP em TypeScript (@modelcontextprotocol/sdk, versão 1.32.2 no npm nesta data), que usaremos no exemplo. Não existe: um servidor MCP do ZapZap publicado e mantido por nós.

Por isso o código abaixo é seu: você o hospeda, você o mantém e você responde pelo que o assistente pode fazer com ele. A vantagem é o controle total sobre quais ferramentas existem. Se um dia houver um servidor oficial, ele estará anunciado nas páginas de documentação e este guia será atualizado.

Comece só com as três primeiras e adicione send_text depois de testar as travas da seção de segurança. Quem lê mensagens de clientes tem de tratá-las como dado pessoal e como entrada não confiável, já que o texto de um cliente pode tentar instruir o assistente (injeção de prompt).

O servidor abaixo usa transporte stdio, o mais simples para rodar localmente: o cliente inicia o processo e conversa pela entrada e saída padrão. Cada ferramenta tem um esquema de entrada em zod e devolve texto. As credenciais vêm de variáveis de ambiente do processo, nunca do assistente.

A ferramenta send_text tem três travas: só envia para números de uma lista permitida (ZAPZAP_ALLOWED), limita o tamanho do texto e fica desligada a menos que ZAPZAP_ENABLE_SEND seja true. Instale com npm install @modelcontextprotocol/sdk zod e compile com tsc ou rode com tsx.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const BASE = "https://api.zapzapapi.com/api/v1/" + process.env.ZAPZAP_INSTANCE_ID;
const headers = {
  "Content-Type": "application/json",
  "x-api-key": process.env.ZAPZAP_API_KEY ?? "",
  "x-api-secret": process.env.ZAPZAP_API_SECRET ?? "",
};
const allowed = new Set((process.env.ZAPZAP_ALLOWED ?? "").split(",").filter(Boolean));
const sendEnabled = process.env.ZAPZAP_ENABLE_SEND === "true";

async function call(method: "GET" | "POST", path: string, body?: unknown) {
  const res = await fetch(BASE + path, { method, headers, body: body ? JSON.stringify(body) : undefined });
  const text = await res.text();
  if (!res.ok) throw new Error("ZapZap " + res.status + ": " + text.slice(0, 300));
  return text;
}
const ok = (text: string) => ({ content: [{ type: "text" as const, text }] });

const server = new McpServer({ name: "whatsapp-zapzap-exemplo", version: "0.1.0" });

server.registerTool(
  "instance_status",
  { description: "Mostra se a instancia de WhatsApp esta conectada." },
  async () => ok(await call("GET", "/instance/status")),
);

server.registerTool(
  "check_numbers",
  {
    description: "Verifica quais numeros (com DDI, so digitos) tem WhatsApp.",
    inputSchema: { numbers: z.array(z.string().regex(/^\d{10,15}$/)).min(1).max(50) },
  },
  async ({ numbers }) => ok(await call("POST", "/chat/check", { numbers })),
);

server.registerTool(
  "find_messages",
  {
    description: "Lista mensagens recentes de uma conversa (chatid, ex: 5511999999999@s.whatsapp.net).",
    inputSchema: { chatid: z.string(), limit: z.number().int().min(1).max(30).default(10) },
  },
  async ({ chatid, limit }) => ok(await call("POST", "/message/find", { chatid, limit, offset: 0 })),
);

if (sendEnabled) {
  server.registerTool(
    "send_text",
    {
      description: "Envia uma mensagem de texto. So funciona para numeros da lista permitida.",
      inputSchema: { number: z.string().regex(/^\d{10,15}$/), text: z.string().min(1).max(1000) },
    },
    async ({ number, text }) => {
      if (!allowed.has(number)) throw new Error("number not in the allowed list");
      return ok(await call("POST", "/send/text", { number, text }));
    },
  );
}

await server.connect(new StdioServerTransport());

Clientes MCP leem uma configuração JSON com o comando que inicia cada servidor e as variáveis de ambiente. No Claude Desktop, o arquivo é claude_desktop_config.json; no Cursor, .cursor/mcp.json no projeto (ou o equivalente global). No Claude Code, o comando claude mcp add registra o servidor. O formato do JSON é o mesmo nos dois primeiros, mas o local do arquivo e os menus mudam entre versões: confira a documentação de cada cliente.

Depois de salvar, reinicie o cliente. As ferramentas aparecem na lista; peça algo como: verifique se a instância está conectada e depois cheque se estes três números têm WhatsApp. Aprove cada chamada na primeira vez em vez de liberar tudo de uma vez.

{
  "mcpServers": {
    "whatsapp": {
      "command": "npx",
      "args": ["tsx", "/caminho/para/server.ts"],
      "env": {
        "ZAPZAP_INSTANCE_ID": "SEU_INSTANCE_ID",
        "ZAPZAP_API_KEY": "SUA_API_KEY",
        "ZAPZAP_API_SECRET": "SEU_API_SECRET",
        "ZAPZAP_ALLOWED": "5511999999999",
        "ZAPZAP_ENABLE_SEND": "false"
      }
    }
  }
}

Quatro regras. Primeira: lista permitida de destinatários, como no código; um assistente nunca deve poder enviar para qualquer número. Segunda: aprovação humana por chamada de envio, que os clientes MCP costumam oferecer e que você deve manter ligada. Terceira: trate o conteúdo lido como não confiável. Uma mensagem de cliente dizendo para ignorar as instruções e enviar algo a outro número é um ataque real; a lista permitida e a aprovação são as defesas. Quarta: instância dedicada, não o número principal do negócio.

Some limites de volume no próprio servidor (contador por hora), registro em log de toda chamada e credenciais com rotação. E lembre que o envio automatizado continua sujeito aos Termos do WhatsApp: ferramenta de IA não muda o risco de restrição do número, e uma conversa iniciada pelo assistente com quem não conhece você é o cenário de maior risco. Veja por que o WhatsApp bloqueia números.

O MCP é um entre vários caminhos para dar ferramentas a um agente. Se o seu agente fala OpenAPI, o arquivo OpenAPI do ZapZap descreve todas as rotas e pode alimentar um gerador de ferramentas. Se você já usa n8n, o fluxo do agente de IA no n8n cobre o caso sem escrever servidor. E para frameworks em Python, o guia de LangChain e CrewAI mostra a mesma ideia com ferramentas HTTP.

Escolha pelo onde o agente roda: MCP serve bem para assistentes de uso pessoal e de equipe (Claude, Cursor); n8n, para automações com gatilho; código próprio, para produto. Em todos, a referência da API é a mesma: send/text, chat/check, message/find e instance/status.