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

• Local (stdio) — uvx evolution-api-mcp runs on your machine and talks to any Evolution API 2.x server you can reach. It supports all three Evolution integrations (WHATSAPP-BAILEYS, WHATSAPP-BUSINESS, EVOLUTION) and can send files from your disk.
• Hosted — https://evolution-mcp.singleflo.com/mcp is served over the internet for Claude.ai, ChatGPT and Codex: 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.

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:

• EVOLUTION_API_URL: the base URL of your Evolution server, for example https://evolution.example.com. A trailing slash is ignored.
• EVOLUTION_INSTANCE_TOKEN: the token of one instance. In Evolution Manager open the instance and copy its token, or use the token returned when the instance was created. The server's global AUTHENTICATION_API_KEY is refused, in both the local and the hosted server, because it controls every instance on that Evolution server.

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 DATABASE_SAVE_DATA_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.

Command-line options of evolution-api-mcp:

Nothing but the JSON-RPC stream reaches stdout while the server runs; diagnostics go to stderr.

Toolsets

Every tool belongs to one toolset. A connection enables some toolsets and sees only their tools. The default is core, which is messaging, chats and contacts; all enables all 13. get_instance_status belongs to instance but is always available, whatever the toolsets.

Local server: EVOLUTION_MCP_TOOLSETS=messaging,chats,groups or --toolsets messaging,chats,groups; presets and toolset names mix (core,groups). An unknown name stops the server at startup. Hosted server: the toolsets are ticked on the consent page and can be changed by signing in again.

Enabled toolsets are not the only thing that decides what a connection sees. tools/list shows exactly the tools a call would not be refused for: toolset enabled, supported by the instance's integration, allowed by the policy, not denied, and, for the irreversible ones, granted. How many that is depends on the connection:

The complete list, one table per toolset with each tool's kind and integrations, is docs/TOOLS.md, generated from the code.

What each integration supports

An Evolution instance uses one integration, and Evolution itself does not offer some operations on some of them. get_instance_status reports which one an instance runs, and a tool called on an integration that lacks it is refused with a message naming the integration it needs. The table counts the tools each toolset offers per integration.

Baileys is WHATSAPP-BAILEYS, a WhatsApp Web session linked to a phone. Business is WHATSAPP-BUSINESS, the WhatsApp Business Platform (Cloud API): it addresses people by phone number only, has no groups, pairing or read receipts, and delivers free-form messages only within 24 hours of the person's last message, after which only approved templates (send_template_message) reach them. Evolution is EVOLUTION, an Evolution channel. The per-tool detail is in docs/TOOLS.md and in the evolution://guide resource.

Tools and resources

Tools follow a few rules that make them predictable for a model and reviewable for a person:

• One tool per operation. Reads and writes are separate tools, and there is no generic "call any endpoint" tool.
• Every tool declares its kind: read, write (private or ephemeral changes such as archiving a chat, labels, presence), destructive (sends something to other people, or replaces or removes something) or irreversible (cannot be undone from this server: logout_instance, delete_message_for_everyone, leave_group, delete_template, delete_chatbot, delete_openai_credential). The MCP hints (readOnlyHint, destructiveHint) are derived from the kind, so a host's approval dialog reflects the real risk. Every tool has openWorldHint set, because each one acts on an external server and, through it, on conversations with other people.
• Tools return compact JSON, never raw Evolution rows. Tokens, passwords and secrets are never returned; a configuration read shows only whether a secret is set. Timestamps are ISO-8601 in the server's display time zone (EVOLUTION_MCP_TIMEZONE; UTC on the hosted server). A result longer than 30,000 characters is cut with a notice that names the remedy.
• A failed call ends in one of three ways: done; refused or failed with "Nothing was changed." or "Nothing was sent."; or UNCERTAIN, when Evolution did not confirm a change that may already ha