Evolution API MCP

MCP server to send and receive WhatsApp messages directly from Claude Code, using Evolution API (open-source, self-hosted).

What it does

• Create and manage WhatsApp instances

• Send text, media, audio, location, contact, poll, sticker, button, and list messages

• Read conversations and received messages

• React to messages, archive chats, mark as read

Related MCP server: mcp-evolution

Prerequisites

• Docker Desktop

• Python 3.11+

• uv (Python package manager)

• Claude Code

Installation

1. Start Evolution API

git clone https://github.com/SEU_USUARIO/evolution-api-mcp.git
cd evolution-api-mcp
docker compose up -d

Wait about 15 seconds and test:

curl http://localhost:8080/

It should return {"status":200,"message":"Welcome to the Evolution API, it is working!"}.

2. Install the MCP server

uv venv
uv pip install -e .

3. Register in Claude Code

claude mcp add evolution-api -s user -- evolution-api-mcp

Or add it manually to the ~/.claude.json file:

{
  "mcpServers": {
    "evolution-api": {
      "type": "stdio",
      "command": "evolution-api-mcp",
      "env": {
        "EVOLUTION_API_URL": "http://localhost:8080",
        "EVOLUTION_API_KEY": "evo_mcp_2024"
      }
    }
  }
}

Windows: the command might need the full path to the .exe: C:/Users/YOUR_USER/evolution-api-mcp/.venv/Scripts/evolution-api-mcp.exe

4. Connect your WhatsApp

1. Open http://localhost:8080/manager/ in your browser

2. Use the Global API Key: evo_mcp_2024

3. Create an instance (e.g., "mywhatsapp")

4. Click on "Generate QR Code"

5. Scan with your WhatsApp: Settings > Linked devices > Link a device

5. Use it!

Reopen Claude Code and start using it:

> envia uma mensagem pro 5511999999999 dizendo oi
> mostra minhas conversas recentes
> envia uma foto pra fulano

Configuration

The default Docker Compose API key is evo_mcp_2024. Change it in docker-compose.yml if you wish.

Structure

evolution-api-mcp/
├── docker-compose.yml          # Evolution API + PostgreSQL
├── pyproject.toml               # Dependencias Python
└── src/evolution_api_mcp/
    ├── server.py                # MCP server (FastMCP + CodeMode)
    ├── client.py                # HTTP client async
    └── tools/
        ├── instance.py          # Criar/conectar/deletar instancias
        ├── messages.py          # Enviar texto, midia, audio, etc.
        └── chat.py              # Listar chats, ler mensagens

Available Tools

Instance

• create_instance - Create WhatsApp instance

• connect_instance - Connect and generate QR code

• fetch_instances - List instances

• connection_state - Check connection status

• logout_instance - Disconnect WhatsApp

• restart_instance - Restart instance

• delete_instance - Delete instance

Messages

• send_text - Send text

• send_media - Send image, video, or document

• send_audio - Send audio/voice note

• send_location - Send location

• send_contact - Send contact card

• send_reaction - React with emoji

• send_poll - Send poll

• send_buttons - Send interactive buttons

• send_list - Send interactive list

• send_sticker - Send sticker

Chat

• find_chats - List conversations

• find_messages - Read messages from a chat

• archive_chat - Archive/unarchive chat

• mark_message_as_read - Mark as read

License

MIT