MCP Evolution API

You can connect Claude to WhatsApp through the Evolution API using this MCP server. It acts as a bridge between your Claude workflows and WhatsApp, enabling you to manage instances, send a variety of messages, handle contacts and groups, and configure webhooks and settings in a cohesive MCP environment.

How to use

Connect an MCP client to the Evolution API MCP server to start automation with WhatsApp. Use the HTTP endpoint to interact with the server from your MCP client or orchestration layer. You can run the server locally or deploy it via Docker Compose, then point your Claude MCP client at the provided URL. Once connected, you can manage WhatsApp instances, send messages (text, media, location, contacts, etc.), and configure webhooks and settings through MCP actions.

How to install

Prerequisites: you will need a runtime environment and tooling similar to the following options. Choose the path that fits your deployment needs.

# Local development setup (using Bun as shown in setup steps)
git clone https://github.com/aiteks-ltda/mcp-evo-api.git
cd mcp-evo-api
bun install
bun run dev

How to install

Alternative local production build and run path.

git clone https://github.com/aiteks-ltda/mcp-evo-api.git
cd mcp-evo-api
bun install
bun run build
bun run dist/main.js

How to install

Docker Compose deployment lets you run the MCP server as a service. Use this when you want a self-contained, orchestrated setup.

git clone https://github.com/aiteks-ltda/mcp-evo-api.git
cd mcp-evo-api
docker-compose up -d

How to install

If you prefer a standalone Docker container, run the container with the required environment variables.

docker run -d -p 3000:3000 -e EVOLUTION_API_URL=yoururl -e EVOLUTION_API_KEY=yourkey --name mcp-evo-api ghcr.io/aiteks-ltda/mcp-evo-api:latest

Configuration and runtime notes

The server expects Evolution API credentials to be provided via environment variables. Create a local .env with the following values, or configure them in your deployment environment.

EVOLUTION_API_URL=https://evo-api.decisao.ai/
EVOLUTION_API_KEY=REPLACE_WITH_YOUR_REAL_KEY

Claude Desktop configuration (HTTP MCP)

To connect Claude Desktop to the locally running MCP server, configure the HTTP MCP with the server URL.

{
  "mcpServers": {
    "evo-api": {
      "url": "http://localhost:3000",
      "args": []
    }
  }
}

Claude Desktop configuration (Docker deployment)

If you are deploying with Docker, point Claude Desktop at the container URL.

{
  "mcpServers": {
    "evo-api": {
      "url": "http://localhost:3000"
    }
  }
}

Available tools

getInfo

Retrieve server information and status to understand the current state of the MCP server.

createInstance

Create a new WhatsApp instance within the Evolution API integration.

fetchInstances

List all configured WhatsApp instances managed by the MCP server.

connectInstance

Establish a connection to a specific WhatsApp instance.

restartInstance

Restart a given WhatsApp instance to recover from errors or apply updates.

getConnectionState

Query the current connection state of an instance.

logoutInstance

Logout and disconnect an active WhatsApp instance.

deleteInstance

Remove an existing WhatsApp instance from the MCP server.

setWebhook

Configure webhooks to receive event updates from the Evolution API.

findWebhook

Retrieve details about configured webhooks.

setSettings

Apply global or per-instance settings for the Evolution API integration.

findSettings

Query current settings for visibility and troubleshooting.

sendPlainText

Send plain text messages to contacts, chats, or groups.

sendMedia

Send media attachments such as images, videos, or documents.

sendWhatsAppAudio

Send audio messages in WhatsApp format.

sendSticker

Send sticker messages to recipients.

sendLocation

Share location details within chats.

sendContact

Share contact cards with recipients.

sendReaction

React to messages with a chosen emoji or reaction.

sendPoll

Create and send polls within a chat.

sendList

Send structured lists with selectable options.

sendButtons

Attach interactive buttons to messages.

findContacts

Search and retrieve contact information.

findChats

Find and list current chats for quick access.

findGroupByJid

Locate a group by its JID (Jabber ID).

fetchAllGroups

Retrieve all groups associated with the account.

findGroupMembers

List members within a specific group.