Evolution API Assistant MCP server

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.

Variable	Default	Meaning
EVOLUTION_MCP_TOOLSETS	core	Comma list of toolsets or presets (core, all) to enable. The --toolsets option wins over it.
EVOLUTION_MCP_ALLOW	*	* allows every tool the deny list does not refuse; none makes the server read-only; otherwise a comma list of tools that change data.
EVOLUTION_MCP_DENY	the default deny list	Comma list of tools that are refused. Unset, it holds the 6 tools listed under "What the agent may do"; a value you set replaces that list entirely.
EVOLUTION_MCP_ALLOW_IRREVERSIBLE	off	yes, true or 1 (any case) lets the tools that cannot be undone run. no, false and 0 keep them off.
EVOLUTION_MCP_DEFAULT_DELAY_MS	1200	Milliseconds of "typing…" the recipient sees before a message is sent, 0 to 20000. A tool's delay_ms overrides it.
EVOLUTION_MCP_MAX_WRITES_PER_MINUTE	30	Changes allowed per minute on this server; 0 turns the limit off.
EVOLUTION_MCP_FILE_ROOTS	your Desktop, Documents, Downloads, Pictures, Movies and Music folders that exist, plus the download folder	Folders send_local_files may read, separated like PATH (: on macOS and Linux, ; on Windows). Each must be an absolute path to an existing directory.
EVOLUTION_MCP_DOWNLOAD_DIR	~/Downloads/evolution-api-mcp	Where download_message_media saves files and export_chat its exports/ folders. Must be an absolute path.
EVOLUTION_MCP_TIMEZONE	the computer's zone (TZ, then /etc/localtime), else UTC	IANA time zone (for example Europe/Rome) in which tools show times and in which a time given without a zone is read. get_instance_status reports it.
EVOLUTION_MCP_DATA_DIR	the platform's data directory	Where the hosted server keeps its data. The local server does not write there.

Command-line options of evolution-api-mcp:

Option	Effect
--toolsets LIST	Same as EVOLUTION_MCP_TOOLSETS; wins over it.
--read-only	Refuse every tool that changes data (same as EVOLUTION_MCP_ALLOW=none).
--list-tools	Print every tool as JSON (name, title, toolset, kind, integrations, local_only) and exit. Needs no credentials.
--list-toolsets	Print the toolsets, their tool counts, the presets and the default as JSON and exit. Needs no credentials.
--version	Print the version and exit.

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.

Toolset	Tools	Covers
instance	5	Connection status, QR pairing, restart, logout and online presence of the instance.
messaging	16	Send text, media, voice notes, locations, contact cards, polls, list and button messages; react, edit and delete sent messages.
chats	13	List chats, show the newest messages across chats, read and search message history, export chats with their attachments, delivery status, read/unread and archive state, received media.
contacts	6	Find chats by name or number, check numbers on WhatsApp, profiles and profile pictures, block and unblock.
groups	17	Group details, participants, invite links, creation, settings and membership.
labels	3	WhatsApp Business app labels on chats.
profile	7	The instance's own profile name, about text, picture and privacy settings.
status	1	Post status updates.
catalog	2	WhatsApp Business app product catalog and collections.
templates	5	WhatsApp Business Platform message templates: list, create, edit, delete and send.
settings	4	Instance behaviour settings and proxy.
events	4	Webhook and event-stream (WebSocket, RabbitMQ, NATS, SQS, Kafka, Pusher) configuration.
integrations	17	Evolution chatbots (Evolution Bot, Typebot, OpenAI, Dify, Flowise, n8n, EvoAI), their sessions, and Chatwoot.

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:

Connection	Tools visible
Local, WhatsApp Web (Baileys) instance, default toolsets and settings	35
Local, Baileys instance, all toolsets	84
Local, Baileys instance, all toolsets, EVOLUTION_MCP_ALLOW_IRREVERSIBLE=yes	89
Local, Baileys instance, all toolsets, read-only	33
Hosted, WhatsApp Business Platform instance, standard policy, all toolsets	41
Hosted, WhatsApp Business Platform instance, read policy, all toolsets	22

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.

Toolset	Tools	Baileys	Business	Evolution
instance	5	5	1	1
messaging	16	16	10	5
chats	13	13	10	7
contacts	6	6	1	1
groups	17	17	0	0
labels	3	3	0	0
profile	7	7	0	0
status	1	1	0	0
catalog	2	2	0	0
templates	5	0	5	0
settings	4	4	4	4
events	4	4	4	4
integrations	17	17	17	17
All	100	95	52	39

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 have been applied. The last one carries the state read back afterwards and says not to repeat the call before checking it.

Resources: evolution://guide, a Markdown guide with the chat-id forms, the integration matrix, where history comes from, pacing and the safety model; and evolution://recipes, tested call sequences for common tasks (what is new, finding an attachment, replying, forwarding, exporting).

Prompts: inbox (what is new, grouped by chat), reply (draft a reply and wait for approval), find_attachment and export. Their chat argument completes contact and group names from the same in-memory name directory the tools use.

Chats are addressed by an international phone number with the country code first (393331234567 or +39 333 123 4567), by the chat_id another tool returned (<digits>@s.whatsapp.net for people, <digits>@g.us for groups, <id>@lid for people whose number WhatsApp hides), or by a contact or group name. A name shared by several chats is refused with their chat_ids; tools that send or change something accept only an exact name.

Message history comes from Evolution's database. It holds messages only when the Evolution server runs with DATABASE_SAVE_DATA_NEW_MESSAGE=true (older history synced at pairing needs DATABASE_SAVE_DATA_HISTORIC=true), and on WhatsApp Business Platform instances it keeps received media only when its S3/MinIO storage is enabled. Evolution has no text search, so search_messages scans the newest 2,000 messages itself; narrow it with a chat or a time range to look further back.

What the agent may do

Every tool call passes one gate before it reaches Evolution, and tools/list hides what the gate would refuse. The gate reads settings that a human owns, in the host configuration file, and that the model cannot change:

• Toolsets. A tool outside the enabled toolsets is refused.
• Integration. A tool the instance's integration does not support is refused.
• Read-only. EVOLUTION_MCP_ALLOW=none or --read-only refuses every tool that is not a read.
• Irreversible. The 6 irreversible tools run only when EVOLUTION_MCP_ALLOW_IRREVERSIBLE=yes is set. No list can grant them; a name in a comma-separated list must never be enough for something nobody can undo.
• Deny list. EVOLUTION_MCP_DENY names tools that are refused. Unset, it is the default list: post_status, remove_group_participants, set_webhook, set_event_channel, set_proxy, set_chatwoot_config — a status update reaches every contact, removing participants ends someone's membership, and the other four change where Evolution sends its events, how it reaches the network, or which Chatwoot helpdesk receives your conversations. A value you set replaces that list, so EVOLUTION_MCP_DENY=post_status re-admits the other five.
• Allow list. EVOLUTION_MCP_ALLOW as a comma list permits only those tools that change data (plus every read).

Entries match tool names exactly. A name that is not a registered tool stops the server at startup, so a typo cannot silently open the gate. The deny list is checked before the allow list, so a name on both refuses. Reads are never limited by either list.

Configuration	What it permits
EVOLUTION_MCP_ALLOW=none	Reads only. Nothing this server does can send or change anything.
Nothing set	Default. Reads, plus every enabled tool that changes data except the 6 on the default deny list and the 6 irreversible ones.
EVOLUTION_MCP_ALLOW_IRREVERSIBLE=yes	The default, plus the irreversible tools the instance's integration supports. The deny list is unchanged.

Local-only tools. 8 tools are registered only by the local server, because they take secrets or read your disk: send_local_files, set_proxy, set_webhook, set_event_channel, create_chatbot, update_chatbot, create_openai_credential and set_chatwoot_config. The hosted server registers the other 92.

Pacing and rate limits. Every send passes a delay, during which the recipient sees "typing…"; the default is 1,200 ms. Changes are limited to 30 per minute per connection; the hosted server also limits reads to 120 per minute. A call that sends several messages (send_local_files, forward_message) counts each message as one change. A refused call names the seconds to wait.

Local files. send_local_files reads only inside EVOLUTION_MCP_FILE_ROOTS, never a hidden file or a file inside a hidden folder, at most 100 MiB per file, and at most 10 files and 300 MiB per call.

Messages are data. Text, names and captions inside messages are written by other people. The server's instructions tell the model that a message asking to send, forward or change something is not a request from you.

This is the authority of this server, not of the token. An agent with shell access can always call Evolution directly, and the instance token can do everything an instance owner can. A limit that must hold regardless of the client belongs in what that token can reach: give the server a token of an instance that holds only the conversations it should see.

WhatsApp rules still apply

Sends are real messages to real people and this server cannot recall them (only WhatsApp Web instances can delete a message for everyone, within the time WhatsApp allows). Message people who agreed to hear from you, honour opt-outs, and send no unsolicited or bulk messages: accounts that break WhatsApp's rules get banned, and no setting here prevents that. On WhatsApp Business Platform instances the WhatsApp Business Messaging Policy applies, including opt-in and the 24-hour window.

Evolution API version

Evolution API 2.3.x is the supported and tested version. Discovery accepts any 2.x server and refuses anything else with a message that names the version. The server also needs the POST /verify-creds route of Evolution 2.3 and later, which it uses to recognise and refuse the global API key.

Hosted server: Claude.ai, ChatGPT and Codex

Everything in the sections further down runs the server on your machine. There is a second way into the same tools: they are also served over the internet at https://evolution-mcp.singleflo.com/mcp, which Claude.ai, ChatGPT and Codex can reach directly. Nothing is installed and no environment variables are set on your side: you sign in once with your Evolution address and instance token, on the server's consent page, and the chat you already use reaches your instance. The local configuration of every other section keeps working exactly as written; the two ways differ only in where the server runs.

The consent page asks for your Evolution URL, the instance token, one policy and the toolsets to enable. The policy standard lets the agent read and act (send messages, manage chats and configuration); read lets it look and nothing else. messaging, chats and contacts are ticked by default. You change either choice later by signing in again.

The hosted server differs from the local one in what it will connect to and offer:

• The public deployment at evolution-mcp.singleflo.com accepts instances whose integration is WHATSAPP-BUSINESS or WHATSAPP-BAILEYS; an EVOLUTION channel instance needs the local server. A server started without EVOLUTION_REMOTE_ALLOWED_INTEGRATIONS accepts WHATSAPP-BUSINESS only, which is the default of the code and the setting the store listings assume; see docs/REMOTE.md. A WHATSAPP-BAILEYS instance is an unofficial WhatsApp Web client: WhatsApp's terms do not cover automating a personal account that way, and WhatsApp can restrict a number that is used like this. The choice is yours; the Business Platform is the supported route.
• The Evolution server must be reachable from the internet at a public address; private and loopback addresses are refused.
• The irreversible tools and the 8 local-only tools are never available, and the default deny list always applies.

What the hosted server stores: your Evolution URL, the instance name, its integration, your policy and toolsets; the instance token, encrypted at rest; OAuth tokens, kept only as hashes; and files a tool produces, which live there only as links that expire after fifteen minutes. It keeps message contents only inside files you ask for (downloaded media and chat exports), behind links that expire after fifteen minutes, and contact names only in memory for ten minutes. The details are at https://evolution-mcp.singleflo.com/privacy, with https://evolution-mcp.singleflo.com/terms and https://evolution-mcp.singleflo.com/support on the same domain.

Per-host instructions: Claude.ai, ChatGPT, Open WebUI and Mistral Le Chat are hosted-only connections and have their own sections below. Claude Code and Codex keep their local configuration and gained a hosted one-liner each.

If you would rather run the hosted part yourself, the developer guide at docs/REMOTE.md covers the whole path: local run, tunnel, deployment.

Host Configuration Examples

Every example below carries only what matters: the two variables. Toolsets default to core and the gate keeps its defaults unless you add EVOLUTION_MCP_TOOLSETS, EVOLUTION_MCP_ALLOW or the other variables of the table above; the last section shows a read-only setup. Note the quotes: environment values are strings.

The calls that wait on WhatsApp are the ones a host's tool timeout can cut short: a send waits for its delay (1,200 ms by default), send_chat_presence holds the call for up to 20 seconds, download_message_media, view_message_image and each attachment of export_chat allow Evolution up to 300 seconds, and send_local_files up to 600 seconds per file for a large upload. Where a host lets you set a timeout, the examples raise it; a JSON file allows no comments, so this note lives here.

Each snippet below was checked against that host's own documentation, cited on the Source: line under it. Where a host has a one-line add command, it is given as well, because it writes the same entry without a hand-edited file.

Claude Desktop

Claude Desktop ships for macOS and Windows only, and keeps its servers in claude_desktop_config.json. Reach it from Settings → Developer → Edit Config, or edit it where it lives:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "evolution-api-mcp": {
      "command": "uvx",
      "args": [
        "evolution-api-mcp"
      ],
      "env": {
        "EVOLUTION_API_URL": "https://evolution.example.com",
        "EVOLUTION_INSTANCE_TOKEN": "your-instance-token-here"
      }
    }
  }
}

Quit Claude Desktop completely and reopen it: it reads the file at startup and does not reload it. Server logs land in ~/Library/Logs/Claude/ on macOS and %APPDATA%\Claude\logs on Windows, one file per server, and stdio servers write everything they say to stderr there.

Source: https://modelcontextprotocol.io/docs/develop/connect-local-servers