# Evolution WhatsApp

> Evolution WhatsApp is an MCP server for communication. Send and read WhatsApp messages through your own Evolution API server. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Platforms:** whatsapp, CLI
- **Repository:** https://github.com/ewertonslv/evolution-whatsapp-mcp
- **MCP Registry name:** io.github.Ewertonslv/evolution-whatsapp-mcp
- **Categories:** [communication](https://ai-powered.com/categories/communication)
- **Listing updated:** 2026-11-18

## About

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.

## Features

- **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

## Install

### Claude Code (Terminal)

```sh
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
```

### Claude Desktop (claude_desktop_config.json)

```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>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```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>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```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>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```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>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```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>"
      }
    }
  }
}
```

## Tools

- `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.

## 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.

## Alternatives

- [TrendRadar](https://ai-powered.com/mcp/trendradar): TrendRadar is an open-source MCP server for communication.
- [Getmitra](https://ai-powered.com/mcp/getmitra): Getmitra is an MCP server for communication.
- [Discord](https://ai-powered.com/mcp/discord-2): Discord is a freemium MCP server for communication.
- [Zoom](https://ai-powered.com/mcp/zoom): Zoom is a freemium MCP server for communication.
- [Email Spam Tester](https://ai-powered.com/mcp/email-spam-tester): Email Spam Tester is a free MCP server for communication.
- [Slack_connect](https://ai-powered.com/mcp/slack-connect): Slack_connect is a freemium MCP server for communication.
- [Postmark](https://ai-powered.com/mcp/postmark): Postmark is a freemium MCP server for communication.
- [Gmail](https://ai-powered.com/mcp/gmail-5): Gmail is a freemium MCP server for communication.

---
Source: https://ai-powered.com/mcp/evolution-whatsapp
