Evolution

This MCP Server connects Evolution API with Claude Desktop via the Model Context Protocol (MCP), enabling you to send messages, manage conversations, and access contacts through a robust, extensible interface. It supports both local stdio operation for Claude Desktop and a HTTP server deployment for production use, giving you flexible ways to integrate WhatsApp with Claude.

How to use

You can run the MCP Server in two primary modes and interact with it from your MCP client. In stdio mode, Claude Desktop communicates directly with the MCP server through standard input/output. In HTTP mode, the MCP server exposes a REST API with a Swagger UI for remote integration. Use the following patterns to accomplish common tasks:

Send a text message or media to a contact, list active chats, search messages, and fetch contact names by number. Retrieve connection status and instance information to monitor health and setup. All operations are exposed as tools that your MCP client can invoke.

How to install

Prerequisites: install Python 3.10 or newer, ensure Claude Desktop is installed for MCP stdio use, and have Docker and Docker Compose available for a full docker-based deployment. You also need an Evolution API instance running or available to connect to.

Choose one of the following installation paths based on how you want to run the MCP Server.

Option A: Quick Start with Docker (recommended for a full deployment) you will run Evolution API and the MCP HTTP Server in one go.

Additional configuration and usage notes

Configuration you’ll typically adjust includes the Evolution API base URL, the API token, and the instance name. When running in HTTP mode, the server is available at the configured base URL and exposes a Swagger UI at /docs. In stdio mode, configure Claude Desktop to point to the MCP server and provide the required environment variables.

Environment variables you’ll commonly set include EVOLUTION_BASE_URL, EVOLUTION_API_TOKEN, EVOLUTION_INSTANCE_NAME, and an optional EVOLUTION_TIMEOUT for request timeouts. These values are passed to the MCP server to establish a secure and persistent connection to Evolution API.

If you run into issues, check that the MCP server process has the expected command and environment, ensure the absolute path to the project is used in configuration, and verify that the Evolution API is reachable from the MCP server host.

Available tools

send_text_message

Sends a text message to a specified number with optional link preview.

send_image

Sends an image to a number with an optional caption.

send_video

Sends a video to a number with an optional caption.

send_document

Sends a document to a number with an optional filename and caption.

send_audio

Sends an audio file to a number.

list_chats

Lists active chats with their names and metadata.

get_chat_messages

Retrieves messages from a specific chat with pagination.

find_messages

Searches messages by a query within a chat.

get_contacts

Lists saved contacts with optional limits.

find_contact

Finds a specific contact by ID.

get_contact_name_by_number

Gets the contact name associated with a phone number.

get_connection_status

Checks the current connection status to Evolution API.

get_instance_info

Returns information about the MCP instance.

set_presence

Sets the presence status for a given number.