Evolution WhatsApp MCP
Ewertonslv/evolution-whatsapp-mcp
WhatsApp para Claude: envie mensagens, gerencie instâncias e automatize conversas via MCP
Ver no GitHubServidor 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-mcp1 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
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.
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
| Tool | Description |
|---|---|
send_text | Send a text message to a phone number |
send_media | Send an image / video / document / audio (URL or base64) |
find_chats | List the conversations on the instance |
find_messages | Read a chat's message history (by phone or JID) |
create_instance | Create a new instance (a WhatsApp connection slot) |
get_qrcode | Get the QR code (base64) to link a WhatsApp number |
connection_status | Check whether the instance is connected |
disconnect_instance | Log the WhatsApp number out of the instance |
configure_webhook | Point 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 var | Required | Description |
|---|---|---|
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:
- "Create a WhatsApp instance called
my-whatsappand show me the QR code." →create_instance+get_qrcode(scan it with your phone). - "Is it connected?" →
connection_status. - "Send 'Your appointment is confirmed ✅' to +55 11 99999-9999." →
send_text. - "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