Skip to content
MCP server

Evolution WhatsApp

Send and read WhatsApp messages through your own Evolution API server

Runs locallyStatus and history
Install
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-mcp

Add 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.Required
  • EVOLUTION_API_KEYEvolution API key, sent as the apikey header.Required
  • EVOLUTION_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.

How AIPoweredBot checks servers