Evolution API MCP server

<!-- mcp-name: io.github.singleflo/evolution-api-mcp -->

Evolution API Assistant

An MCP server that operates one Evolution API v2 instance, which is one WhatsApp number: it reads chats and message history, sends messages and media, manages groups, contacts, labels, templates and profile, and configures the instance, its webhooks and its chatbots. 100 tools, one per operation, grouped in 13 toolsets you switch on as needed. It talks only to the Evolution server you point it at, with that instance's own token.

Evolution API Assistant is an independent project by Persevida SL, not affiliated with or endorsed by Meta, WhatsApp or the Evolution API project.

Two ways to use it

reach. It supports all three Evolution integrations (WHATSAPP-BAILEYS, WHATSAPP-BUSINESS, EVOLUTION) and can send files from your disk.

• Local (stdio) — uvx evolution-api-mcp runs on your machine and talks to any Evolution API 2.x server you can

nothing to install, you sign in once with your Evolution URL and instance token. The public hosted server accepts instances whose integration is WHATSAPP-BUSINESS (the official WhatsApp Business Platform) or WHATSAPP-BAILEYS (a WhatsApp Web session), and never offers the tools that take secrets or cannot be undone. See "Hosted server" below.

• Hosted — https://evolution-mcp.singleflo.com/mcp is served over the internet for Claude.ai, ChatGPT and Codex:

Quickstart

Install with your AI agent. If you already have an AI coding assistant — Claude Code, Claude Desktop, Cursor, opencode, any of the hosts below — paste this link into your agent and ask it to set up Evolution API Assistant: https://raw.githubusercontent.com/singleflo/evolution-api-mcp/main/docs/INSTALL-WITH-YOUR-AGENT.md That page is written for the agent rather than for you: it asks you for the Evolution URL and the instance token, installs uv, writes the configuration file its own host reads, and verifies the connection. The manual route is below.

1. Install

Run the server directly:

uvx evolution-api-mcp

Or install it into your environment:

uv pip install evolution-api-mcp

Installing from source for development remains possible:

uv pip install git+https://github.com/singleflo/evolution-api-mcp

The server needs Python 3.10 or later. uvx fetches a suitable interpreter by itself.

2. Configure environment variables

Two variables are all a working setup needs:

slash is ignored.

• EVOLUTIONAPIURL: the base URL of your Evolution server, for example https://evolution.example.com. A trailing

or use the token returned when the instance was created. The server's global AUTHENTICATIONAPIKEY is refused, in both the local and the hosted server, because it controls every instance on that Evolution server.

• EVOLUTIONINSTANCETOKEN: the token of one instance. In Evolution Manager open the instance and copy its token,

The instance name and its integration are discovered from the token; you never type them. A missing variable is reported when a tool is called, not at startup, so the server still starts and lists its tools while you fix the configuration. Evolution resolves instance tokens only while it runs with DATABASESAVEDATA_INSTANCE=true (its default); with false it answers 401 and the server says so.

Everything else is optional. A blank value counts as unset for every variable. A value the server cannot accept stops it at startup with exit code 2 and a message on stderr naming the variable and what it accepts.

Shortened. The full README is on GitHub.