convez.ai
MCP ServerIntegração & APIsIntermediário
Ewertonslv

Evolution WhatsApp MCP

Ewertonslv/evolution-whatsapp-mcp

WhatsApp para Claude: envie mensagens, gerencie instâncias e automatize conversas via MCP

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que integra WhatsApp (via Evolution API) ao Claude, permitindo enviar/ler mensagens, gerenciar mídia e controlar instâncias de conexão. Funciona como um bridge stateless que conecta seu agente IA diretamente ao WhatsApp sem necessidade de hospedagem permanente.

Instalação

$npx convez-ai Ewertonslv/evolution-whatsapp-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 semana
Versão
v0.1.2
Issues abertas
0
Contribuidores
1

Casos de uso

  • Automação de atendimento ao cliente via WhatsApp integrado com IA
  • Agentes IA que leem e respondem mensagens em tempo real
  • Gestão multicanal de comunicação com WhatsApp como endpoint

Veredito

Integração sólida e pronta para produção, extraída de um SaaS real. Exige Evolution API rodando separadamente (Docker ou VPS), mas a configuração é clara e o MCP em si é robusto para casos de automação de WhatsApp sem infraestrutura complexa.

README

A tradução para o português deste README ainda está na fila.

evolution-whatsapp-mcp

An MCP server that gives Claude (and any MCP client) hands on WhatsApp — send and read messages, send media, and manage connections through the Evolution API. Wire it into Claude Desktop/Code and your AI agent can connect a WhatsApp number and have real conversations.

CI Node License: MIT

Extracted and generalized from a production WhatsApp integration (a multi-tenant clinic SaaS), so the messaging/instance layer is battle-tested — not a toy.

Architecture & where it runs

Claude (Desktop/Code)        evolution-whatsapp-mcp          Evolution API        WhatsApp
     [MCP client]   ──stdio──►   (this package)    ──HTTP──►   (gateway)  ──────►  (phone)
  • This MCP server runs locally, on demand — nothing to host. Your MCP client (Claude Desktop/Code) spawns it as a child process over stdio (npx evolution-whatsapp-mcp); it starts when the client needs it and exits when the client closes. No open ports, no deployment.
  • The Evolution API is the part that must stay running, because it holds the WhatsApp session (like WhatsApp Web — if it goes down, the number disconnects). Run it locally via Docker to try things out, or on a small VPS if you need it online 24/7 (e.g. to receive messages via webhook). This server only needs its URL + API key.
  • The server is stateless — no database, no message storage. It's just a thin, secure bridge from your MCP client to the Evolution API.

Tools

ToolDescription
send_textSend a text message to a phone number
send_mediaSend an image / video / document / audio (URL or base64)
find_chatsList the conversations on the instance
find_messagesRead a chat's message history (by phone or JID)
create_instanceCreate a new instance (a WhatsApp connection slot)
get_qrcodeGet the QR code (base64) to link a WhatsApp number
connection_statusCheck whether the instance is connected
disconnect_instanceLog the WhatsApp number out of the instance
configure_webhookPoint the instance webhook to a public URL

Every tool takes an optional instance argument; if omitted it falls back to EVOLUTION_DEFAULT_INSTANCE.

Prerequisites

A running Evolution API server (v2.x) and its API key. The quickest way to run one locally is the official Docker image — use local Docker to try it out, or a VPS for 24/7 operation:

docker run -d --name evolution -p 8080:8080 \
  -e AUTHENTICATION_API_KEY=your-evolution-api-key \
  atendai/evolution-api:latest

Install & configure

Add it to your MCP client. For Claude Desktop / Claude Code (mcpServers config):

{
  "mcpServers": {
    "whatsapp": {
      "command": "npx",
      "args": ["-y", "evolution-whatsapp-mcp"],
      "env": {
        "EVOLUTION_API_URL": "http://localhost:8080",
        "EVOLUTION_API_KEY": "your-evolution-api-key",
        "EVOLUTION_DEFAULT_INSTANCE": "my-whatsapp"
      }
    }
  }
}
Env varRequiredDescription
EVOLUTION_API_URL✅Base URL of your Evolution API server
EVOLUTION_API_KEY✅Evolution API key (sent as the apikey header)
EVOLUTION_DEFAULT_INSTANCE—Default instance when a tool omits instance

Example flow (end to end)

Ask Claude:

  1. "Create a WhatsApp instance called my-whatsapp and show me the QR code." → create_instance + get_qrcode (scan it with your phone).
  2. "Is it connected?" → connection_status.
  3. "Send 'Your appointment is confirmed ✅' to +55 11 99999-9999." → send_text.
  4. "What did they reply?" → find_messages.

Development

npm install
npm run build      # tsc → dist/
npm test           # vitest (mocks the Evolution API; no server needed)
npm run lint       # tsc --noEmit

Inspect the server locally with the MCP Inspector:

EVOLUTION_API_URL=http://localhost:8080 EVOLUTION_API_KEY=key \
  npx @modelcontextprotocol/inspector node dist/index.js

How it works

A thin REST client (src/evolution.ts) wraps the Evolution endpoints and authenticates with the apikey header. src/tools.ts registers each operation as an MCP tool with a zod input schema; src/index.ts serves them over stdio. No business logic, no database — just a clean bridge between an MCP client and the Evolution API.

License

MIT © Ewerton Silva

Ver o original no GitHub

Bom para

Relacionados