Evolution WhatsApp
Send and read WhatsApp messages through your own Evolution API server
- Platforms
- whatsapp, CLI
- Runs
- Locally
- Version
- 0.3.1
- Listing updated
- today
Similar MCP servers
About Evolution WhatsApp
Evolution WhatsApp is an MCP server for communication. It runs locally on your machine and is started by your AI client.
This server does not talk to WhatsApp directly. It forwards calls to an Evolution API gateway that you run, either locally in Docker or on a small VPS, and that gateway holds the WhatsApp session. The MCP server itself is stateless, starts on demand over stdio and keeps no messages.
The README is explicit about prompt-injection risk, since a received message could try to steer the model. Environment settings let you hide every write tool, require a human confirmation dialog before sends and changes, or limit sends to a list of phone numbers. Confirmation previews mask the number, show up to 200 characters, and refuse the write if the client can't show a dialog.
Other limits include a 1-200 cap on chat and message listings, truncation of responses over 100,000 characters, https-only webhooks and a warning if the API key would travel over plain http. The client code originated in a clinic SaaS and was last checked against Evolution API 2.3.7 in October 2026.
Install
Run in a terminal
claude mcp add evolution-whatsapp-mcp --env EVOLUTION_API_URL='<EVOLUTION_API_URL>' --env EVOLUTION_API_KEY='<EVOLUTION_API_KEY>' -- npx -y evolution-whatsapp-mcpAdd to claude_desktop_config.json
{
"mcpServers": {
"evolution-whatsapp-mcp": {
"command": "npx",
"args": [
"-y",
"evolution-whatsapp-mcp"
],
"env": {
"EVOLUTION_API_URL": "<EVOLUTION_API_URL>",
"EVOLUTION_API_KEY": "<EVOLUTION_API_KEY>"
}
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"evolution-whatsapp-mcp": {
"command": "npx",
"args": [
"-y",
"evolution-whatsapp-mcp"
],
"env": {
"EVOLUTION_API_URL": "<EVOLUTION_API_URL>",
"EVOLUTION_API_KEY": "<EVOLUTION_API_KEY>"
}
}
}
}Add to .vscode/mcp.json
{
"servers": {
"evolution-whatsapp-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"evolution-whatsapp-mcp"
],
"env": {
"EVOLUTION_API_URL": "<EVOLUTION_API_URL>",
"EVOLUTION_API_KEY": "<EVOLUTION_API_KEY>"
}
}
}
}Add to ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"evolution-whatsapp-mcp": {
"command": "npx",
"args": [
"-y",
"evolution-whatsapp-mcp"
],
"env": {
"EVOLUTION_API_URL": "<EVOLUTION_API_URL>",
"EVOLUTION_API_KEY": "<EVOLUTION_API_KEY>"
}
}
}
}Add to your client's MCP settings (most use this shape)
{
"mcpServers": {
"evolution-whatsapp-mcp": {
"command": "npx",
"args": [
"-y",
"evolution-whatsapp-mcp"
],
"env": {
"EVOLUTION_API_URL": "<EVOLUTION_API_URL>",
"EVOLUTION_API_KEY": "<EVOLUTION_API_KEY>"
}
}
}
}Using several servers? Build one config file with the MCP config generator.
Configuration
EVOLUTION_API_URLBase URL of your Evolution API server, e.g. http://localhost:8080. Use https outside localhost.RequiredEVOLUTION_API_KEYEvolution API key, sent as the apikey header.RequiredEVOLUTION_DEFAULT_INSTANCEDefault instance used when a tool call omits the instance argument.EVOLUTION_TIMEOUT_MSPer-request timeout in milliseconds (default 30000).EVOLUTION_READ_ONLYSet to true to hide every tool that sends or changes state (send_text, send_media, create_instance, disconnect_instance, configure_webhook).EVOLUTION_CONFIRM_WRITESSet to true to require a human confirmation (elicitation dialog) before send_text, send_media, create_instance, disconnect_instance or configure_webhook run. Clients that can show no dialog are refused. Default false; an unrecognised value counts as true and prints a warning.EVOLUTION_ALLOWED_NUMBERSComma-separated phone numbers that send_text and send_media may reach. Empty means no restriction.
Tools this server provides (9)
Taken from the project documentation; the running server may differ.
- send_text
- Sends a text message to a phone number.
- send_media
- Sends an image, video, document or audio by URL or base64.
- find_chats
- Lists conversations on the instance.
- find_messages
- Reads a chat's message history.
- create_instance
- Creates a new WhatsApp connection instance.
- get_qrcode
- Gets the QR code to link a number.
- connection_status
- Checks whether the instance is connected.
- disconnect_instance
- Logs the number out of the instance.
- configure_webhook
- Points the instance webhook to a public URL.
What it does
- Send text and media
- Sends messages, images, video, documents or audio.
- Read chats and history
- Lists conversations and reads message history with paging.
- Instance management
- Creates instances, fetches the QR code and checks connection status.
- Read-only mode
- EVOLUTION_READ_ONLY hides every tool that sends or changes state.
- Confirm before writing
- Optional human confirmation before each write.
- Number allowlist
- Restricts which numbers can receive messages.
Good for
- Let an assistant draft and send appointment confirmations
- Read a chat's recent history to summarise it
- Link a WhatsApp number by QR code from chat
- Run a read-only assistant over a monitored inbox
More servers for the same service
Evolution WhatsApp FAQ
Do I need to host anything?
You need a running Evolution API v2 server; the MCP server itself runs locally on demand.
How can I stop it sending messages?
Set EVOLUTION_READ_ONLY to hide the write tools, or use EVOLUTION_ALLOWED_NUMBERS.
What tools are included?
Nine: send_text, send_media, find_chats, find_messages, create_instance, get_qrcode, connection_status, disconnect_instance and configure_webhook.
Does it store messages?
No. It is stateless with no database.
How do I add Evolution WhatsApp to Claude Code?
Run this command in your terminal: claude mcp add evolution-whatsapp-mcp --env EVOLUTION_API_URL='<EVOLUTION_API_URL>' --env EVOLUTION_API_KEY='<EVOLUTION_API_KEY>' -- npx -y evolution-whatsapp-mcp
What are the best alternatives to Evolution WhatsApp?
The closest alternatives to Evolution WhatsApp are TrendRadar, Getmitra, Discord, Zoom and Email Spam Tester.
Where this comes from
- Description: written from the project's README.
- Install steps: from the official MCP Registry entry.

