@alltomatos/izapia-mcp

Servidor MCP (Model Context Protocol) para a izapia, a API WhatsApp para desenvolvedores. Conecte seu agente de IA (Claude Code, Cursor, Windsurf, Claude Desktop, …) e ele passa a enviar mensagens, gerenciar sessões/grupos/webhooks e construir integrações WhatsApp sem sair do chat — consultando o contrato real da API em vez de alucinar endpoints.

Instalação

// .mcp.json (ou a config MCP do seu cliente)
{
  "mcpServers": {
    "izapia": {
      "command": "npx",
      "args": ["-y", "@alltomatos/izapia-mcp"],
      "env": {
        "IZAPIA_API_KEY": "izapia_sk_..."
      }
    }
  }
}

Pegue sua IZAPIA_API_KEY no painel da sua conta izapia. Sem ela, as tools que chamam a API ao vivo (envio, sessões, grupos, webhooks) ficam indisponíveis — as tools de consulta ao contrato (izapia_search_endpoints, izapia_get_endpoint, izapia_get_events) funcionam mesmo sem chave.

O que seu agente ganha

Modo padrão = leitura. Por segurança, tools que enviam mensagem, criam sessão ou mudam configuração só ficam disponíveis com "env": { "IZAPIA_MCP_MODE": "write" } — assim seu agente não dispara um envio real sem você habilitar explicitamente.

Descobrir a API (sem gastar tokens alucinando)

| Tool | Para que serve | | --- | --- | | izapia_search_endpoints | "Como eu marco uma mensagem como lida?" — busca no contrato real por palavra-chave/tag e devolve o endpoint certo. | | izapia_get_endpoint | Schema completo (params, body, resposta) de um endpoint específico — o agente monta a chamada certa de primeira. | | izapia_get_events | Catálogo de eventos que chegam por webhook/SSE (message.received, call.offer, …) e o formato exato do payload. | | izapia_verify_webhook_signature | Valida a assinatura X-izapia-Signature de um webhook recebido — útil pra debugar integração de webhook. | | izapia_capabilities | Mostra o modo atual (read/write) e como habilitar escrita. |

Operar o WhatsApp (modo write)

| Tool | Para que serve | | --- | --- | | izapia_create_session / izapia_pair_session | Cria uma conexão e gera o QR code de pareamento. | | izapia_send_text / izapia_send_media | Envia mensagem de texto ou mídia. | | izapia_list_sessions / izapia_list_groups / izapia_list_contacts | Consulta sessões, grupos e contatos. | | izapia_create_group | Cria um grupo com os participantes informados. | | izapia_set_presence | Define presença (online/digitando/etc.). | | izapia_set_webhook / izapia_get_webhook | Configura pra onde a izapia envia os eventos recebidos. | | izapia_watch_events | Observa eventos em tempo real por alguns segundos — ótimo pra testar se um webhook está chegando. | | izapia_request | Chama qualquer endpoint da API (todas as ~104 rotas), pra tudo que não tem um atalho dedicado acima. |

Toda tool de escrita aceita dry_run: true — o agente monta e mostra a requisição exata sem executar, útil pra revisar antes de confirmar.

Exemplos do que pedir ao seu agente

• "Cria uma sessão izapia e me mostra o QR code pra parear meu WhatsApp."
• "Envia 'Pedido confirmado!' pro número 5585999999999."
• "Configura um webhook na minha sessão apontando pra https://meu-app.com/webhook, só pra eventos de mensagem recebida."
• "Observa os próximos eventos por 20 segundos pra eu ver se o webhook tá chegando certo."
• "Qual o schema de resposta do endpoint de criar grupo?"

Configuração (env)

| Env | Default | Descrição | | --- | --- | --- | | IZAPIA_API_KEY | — | Sua chave de API (izapia_sk_…). Nunca é logada. | | IZAPIA_MCP_MODE | read | read (só consulta) ou write (habilita envio/gerenciamento). | | IZAPIA_MCP_ALLOW_DESTRUCTIVE | false | Habilita ações destrutivas (logout, exclusão) via izapia_request. | | IZAPIA_MCP_ALLOW | — | Lista (CSV) de tools permitidas, se você quiser restringir ainda mais. | | IZAPIA_BASE_URL | https://api.izapia.com | Normalmente não precisa mexer. |

Também vem com uma Agent Skill

O pacote inclui uma Agent Skill com o guia completo da API (auth, todos os endpoints por domínio, eventos, limites) pra agentes que preferem ler documentação em vez de chamar tools. Instale com:

npx -y @alltomatos/izapia-mcp install-skill

Saiba mais

• Documentação completa da API: docs.izapia.com
• Site: izapia.com

pnpm install
pnpm gen        # vendora os specs (../docs/{openapi-public.yaml,events-catalog.json}) + gera tipos + cheatsheet da skill
pnpm typecheck
pnpm lint
pnpm test
pnpm build      # gera dist/cli.js (bin: izapia-mcp)
pnpm smoke      # sobe o binário buildado via stdio (end-to-end)

Sincronia com o contrato (drift): docs/openapi.yaml → docs/openapi-public.yaml (via go run ./cmd/openapigen) e internal/events/events.go → docs/events-catalog.json (via go run ./cmd/eventsgen) → mcp/assets/ (via pnpm gen:spec) → src/izapia/generated/schema.d.ts + skill/izapia-api/references/*.md (via pnpm gen:types / pnpm gen:skill). Quem editar o OpenAPI ou internal/events precisa rodar o gerador Go correspondente e pnpm gen neste pacote (ci-mcp.yml falha se ficarem desatualizados).

Publicação: .github/workflows/publish-mcp.yml dispara em tags mcp-v* e publica com pnpm publish --access public, usando o secret NPM_TOKEN.

git tag mcp-vX.Y.Z
git push origin mcp-vX.Y.Z

Segurança: o backend da izapia não aplica escopos por API key hoje — a chave tem poder total no tenant. O modo read-default e o dry_run deste servidor são a única salvaguarda no lado do MCP; trate a chave como segredo.