Which integrations are available for this server?

Provides tools for managing WhatsApp instances, including sending messages, reading chat history, managing contacts, groups, profiles, labels, templates, and calls via the Evolution API.

How do I use MCP-WHATSAPP-EVO?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP-WHATSAPP-EVO send "Hello!" to +1234567890" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

MCP-WHATSAPP-EVO

by jppeiro90

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

MCP-WHATSAPP-EVO

A Model Context Protocol (MCP) server that exposes the full WhatsApp surface of the Evolution API to MCP clients such as Claude Code, Claude Desktop and Cursor.

Unlike most Evolution MCP servers, this one can read message history (find_messages) and covers ~69 tools across instances, messaging, chats, profile, groups, labels, templates and calls.

Transport: stdio
Runtime: Node.js ≥ 18 (no Bun required)
Auth: the global Evolution API key, sent as the apikey header

Tools

Category	Tools
Instances (9)	`fetch_evolution_instances`, `get_connection_state`, `create_evolution_instance`, `connect_evolution_instance`, `restart_evolution_instance`, `set_evolution_presence`, `logout_evolution_instance`, `delete_evolution_instance`, `get_evolution_info`
Send messages (13)	`send_plain_text`, `send_media`, `send_whatsapp_audio`, `send_sticker`, `send_location`, `send_contact`, `send_reaction`, `send_poll`, `send_list`, `send_buttons`, `send_status`, `send_ptv`, `send_template`
Chat & history (15)	`find_messages`, `find_chats`, `find_contacts`, `find_chat_by_remote_jid`, `find_status_message`, `check_whatsapp_numbers`, `mark_message_as_read`, `mark_chat_unread`, `archive_chat`, `delete_message_for_everyone`, `update_message`, `send_chat_presence`, `update_block_status`, `fetch_profile_picture_url`, `get_base64_from_media_message`
Profile (8)	`fetch_business_profile`, `fetch_profile`, `update_profile_name`, `update_profile_status`, `update_profile_picture`, `remove_profile_picture`, `fetch_privacy_settings`, `update_privacy_settings`
Groups (16)	`fetch_all_groups`, `find_group_by_jid`, `find_group_members`, `create_group`, `update_group_subject`, `update_group_picture`, `update_group_description`, `fetch_invite_code`, `fetch_invite_info`, `accept_invite_code`, `send_group_invite`, `revoke_invite_code`, `update_participant`, `update_group_setting`, `toggle_ephemeral`, `leave_group`
Settings & webhook (4)	`set_evolution_settings`, `get_evolution_settings`, `set_evolution_webhook`, `get_evolution_webhook`
Labels / Templates / Calls (5)	`find_labels`, `handle_label`, `find_template`, `create_template`, `offer_call`

*_template and send_template only work on WHATSAPP-BUSINESS (Cloud API) instances, not Baileys.

Related MCP server: mcp-evolution-api

Setup

git clone https://github.com/your-username/MCP-WHATSAPP-EVO.git
cd MCP-WHATSAPP-EVO
npm install
npm run build        # produces dist/main.cjs

Configuration is done with two environment variables (see .env.example):

Variable	Description
`EVOLUTION_API_URL`	Base URL of your Evolution API (no trailing slash)
`EVOLUTION_API_KEY`	The global `AUTHENTICATION_API_KEY` of your server

Use with Claude Code

claude mcp add evolution-whatsapp -s user \
  -e EVOLUTION_API_URL=https://evo.example.com \
  -e EVOLUTION_API_KEY=your-key \
  -- node /absolute/path/to/MCP-WHATSAPP-EVO/dist/main.cjs

On Windows, point at node.exe and the .cjs explicitly:

claude mcp add evolution-whatsapp -s user \
  -e EVOLUTION_API_URL=https://evo.example.com \
  -e EVOLUTION_API_KEY=your-key \
  -- "C:\Program Files\nodejs\node.exe" "C:\path\to\MCP-WHATSAPP-EVO\dist\main.cjs"

Then claude mcp list should show it as ✔ Connected. Restart the client to load the tools.

Use with other MCP clients

This is a standard MCP server over stdio, so it works with any MCP-compatible client. They all use the same configuration shape — only the file/UI where you put it changes:

{
  "mcpServers": {
    "evolution-whatsapp": {
      "command": "node",
      "args": ["/absolute/path/to/MCP-WHATSAPP-EVO/dist/main.cjs"],
      "env": {
        "EVOLUTION_API_URL": "https://evo.example.com",
        "EVOLUTION_API_KEY": "your-key"
      }
    }
  }
}

On Windows, use the full path to node.exe as command and double-escape backslashes in the path ("C:\\path\\to\\MCP-WHATSAPP-EVO\\dist\\main.cjs").

Where to put that config, per client:

Client	Where
Claude Desktop	`claude_desktop_config.json` — macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`
Cursor	`~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project)
Windsurf	`~/.codeium/windsurf/mcp_config.json` (Settings → Cascade → MCP)
VS Code (Copilot/Agent)	`.vscode/mcp.json` — note: keys go under a top-level `"servers"` object instead of `"mcpServers"`
Cline / Roo Code (VS Code ext.)	the extension's MCP Servers → Configure panel (same JSON)
Continue	`~/.continue/config.yaml` under `mcpServers` (YAML form of the same fields)
Zed	`settings.json` under `"context_servers"`
Any other MCP client	point it at `command: node`, `args: [".../dist/main.cjs"]`, and pass the two env vars

After editing the config, restart the client so it spawns the server and loads the tools. The only requirements are Node.js ≥ 18 on the machine and the two environment variables.

Notes on phone numbers & JIDs

Numbers use the international format without +, e.g. 5491112345678.
JIDs are <number>@s.whatsapp.net for users and <id>@g.us for groups.
find_messages is paginated: use page and offset (messages per page).

Security

The Evolution API key grants full control over every instance on the server (including personal numbers). Treat it as a secret, scope a dedicated instance/key for automation when possible, and never commit your .env.

Architecture

src/
  lib/
    client.ts      # generic Evolution HTTP client (apikey header, error mapping)
    defineTool.ts  # helper: Zod schema -> MCP tool with parsing + error handling
  tools/
    instances.ts messages.ts chat.ts profile.ts groups.ts settings.ts extras.ts
    index.ts       # aggregates every category into createTools()
  main.ts          # MCP server bootstrap (stdio)

Adding a new endpoint is one defineTool({ name, description, schema, run }) block that calls getClient().request(method, path, { data, params }).

License

MIT — see LICENSE.

Available Tools

70 tools

accept_invite_codeB

Join a group using an invite code.

Inputs: inviteCode (required), instanceName (required).

archive_chatC

Archive or unarchive a chat.

Inputs: chat (required), archive (required), instanceName (required), lastMessage.

check_whatsapp_numbersA

Check whether one or more phone numbers are registered on WhatsApp.

Inputs: numbers (required), instanceName (required).

connect_evolution_instanceB

Connect a WhatsApp instance and get the pairing code / QR code base64.

Inputs: instanceName (required), number.

create_evolution_instanceB

Create a new WhatsApp instance. Returns the instance hash/apikey and (for Baileys) a QR code to connect.

Inputs: instanceName (required), number, qrcode, msgCall, +7 more.

create_groupC

Create a new group with a subject and participants.

Inputs: subject (required), instanceName (required), participants (required), description.

create_templateB

Create a message template (WHATSAPP-BUSINESS / Cloud API only).

Inputs: name (required), language (required), instanceName (required), category, +1 more.

delete_evolution_instanceB

Permanently delete a WhatsApp instance.

Inputs: instanceName (required).

delete_message_for_everyoneC

Delete a message for everyone in the chat.

Inputs: id (required), fromMe (required), remoteJid (required), instanceName (required), +1 more.

fetch_all_groupsB

List all groups the instance belongs to.

Inputs: instanceName (required), getParticipants.

fetch_business_profileB

Fetch the WhatsApp Business profile of a number.

Inputs: number (required), instanceName (required).

fetch_evolution_instancesA

List all WhatsApp instances (or a specific one by name) with their connection status, owner and counts.

Inputs: instanceName.

fetch_invite_codeB

Get the invite link/code of a group.

Inputs: groupJid (required), instanceName (required).

fetch_invite_infoA

Get group info from an invite code (without joining).

Inputs: inviteCode (required), instanceName (required).

fetch_privacy_settingsB

Fetch the privacy settings of the instance.

Inputs: instanceName (required).

fetch_profileB

Fetch the profile (name, status, picture) of a number.

Inputs: number (required), instanceName (required).

fetch_profile_picture_urlC

Get the profile picture URL of a contact.

Inputs: number (required), instanceName (required).

find_chat_by_remote_jidB

Find a single chat by its remoteJid.

Inputs: remoteJid (required), instanceName (required).

find_chatsB

List WhatsApp chats with their metadata (name, last message timestamp, unread count).

Inputs: instanceName (required), where.

find_contactsB

Search contacts by id (phone/JID) or name.

Inputs: instanceName (required), where.

find_group_by_jidA

Get the info of a group by its JID.

Inputs: groupJid (required), instanceName (required).

find_group_membersB

List the participants of a group.

Inputs: groupJid (required), instanceName (required).

find_labelsA

List the chat labels of an instance.

Inputs: instanceName (required).

find_messagesA

Read the message history of a chat. Filter by the contact's remoteJid (e.g. 5491112345678@s.whatsapp.net or a group ...@g.us). Results are paginated.

Inputs: remoteJid (required), instanceName (required), page, offset.

find_status_messageC

Retrieve status (story) messages.

Inputs: instanceName (required), where.

find_templateA

List the message templates of an instance (WHATSAPP-BUSINESS only).

Inputs: instanceName (required).

get_base64_from_media_messageC

Download a media message and return it as base64.

Inputs: message (required), instanceName (required), convertToMp4.

get_connection_stateA

Check the connection state of a WhatsApp instance (open = connected, close/connecting otherwise).

Inputs: instanceName (required).

get_evolution_infoA

Get basic information about the Evolution API server (version, status).

Inputs: no named parameters.

get_evolution_settingsB

Get the current behaviour settings of an instance.

Inputs: instanceName (required).

get_evolution_webhookC

Get the current webhook configuration of an instance.

Inputs: instanceName (required).

handle_labelB

Add or remove a label from a chat.

Inputs: action (required), number (required), labelId (required), instanceName (required).

leave_groupC

Leave a group.

Inputs: groupJid (required), instanceName (required).

logout_evolution_instanceA

Log out a WhatsApp instance (disconnects the device without deleting the instance).

Inputs: instanceName (required).

mark_chat_unreadC

Mark a chat as unread.

Inputs: chat (required), instanceName (required), lastMessage.

mark_message_as_readC

Mark one or more messages as read.

Inputs: instanceName (required), readMessages (required).

offer_callA

Offer a (fake) WhatsApp call to a number — rings the recipient without a real call.

Inputs: number (required), instanceName (required), isVideo, callDuration.

remove_profile_pictureC

Remove the profile picture of the instance.

Inputs: instanceName (required).

restart_evolution_instanceB

Restart a WhatsApp instance.

Inputs: instanceName (required).

revoke_invite_codeB

Revoke and regenerate a group's invite code.

Inputs: groupJid (required), instanceName (required).

send_buttonsC

Send a message with interactive buttons.

Inputs: title (required), number (required), buttons (required), description (required), +6 more.

send_chat_presenceB

Send a typing/recording presence to a chat (composing, recording or paused).

Inputs: number (required), presence (required), instanceName (required), delay.

send_contactC

Send one or more contact cards (vCards).

Inputs: number (required), contact (required), instanceName (required), delay, +3 more.

send_group_inviteC

Send a group invite to one or more numbers.

Inputs: numbers (required), groupJid (required), description (required), instanceName (required).

send_listC

Send an interactive list message.

Inputs: title (required), number (required), sections (required), buttonText (required), +7 more.

send_locationC

Send a location message.

Inputs: name (required), number (required), address (required), latitude (required), +6 more.

send_mediaB

Send a media message (image, video, audio or document) by URL or base64.

Inputs: media (required), number (required), mediatype (required), instanceName (required), +7 more.

send_plain_textC

Send a plain text message to a WhatsApp number.

Inputs: text (required), number (required), instanceName (required), delay, +4 more.

send_pollC

Send a poll message.

Inputs: name (required), number (required), values (required), instanceName (required), +5 more.

send_ptvB

Send a PTV (round video note) by URL or base64.

Inputs: video (required), number (required), instanceName (required), delay, +3 more.

send_reactionC

React to a message with an emoji.

Inputs: instanceName (required), reactionMessage (required).

send_statusC

Post a WhatsApp status/story (text, image or audio).

Inputs: instanceName (required), statusMessage (required).

send_stickerB

Send a sticker by URL or base64.

Inputs: number (required), sticker (required), instanceName (required), delay, +3 more.

send_templateA

Send an approved WhatsApp Business template message. Only works on WHATSAPP-BUSINESS (Cloud API) instances.

Inputs: name (required), number (required), language (required), instanceName (required), +1 more.

send_whatsapp_audioC

Send a WhatsApp voice note (PTT) by URL or base64.

Inputs: audio (required), number (required), instanceName (required), delay, +4 more.

set_evolution_presenceB

Set the global presence of an instance (available or unavailable).

Inputs: presence (required), instanceName (required).

set_evolution_settingsC

Update the behaviour settings of an instance.

Inputs: instanceName (required), msgCall, readStatus, rejectCall, +4 more.

set_evolution_webhookB

Configure the webhook of an instance (where Evolution POSTs events).

Inputs: url (required), enabled (required), instanceName (required), events, +2 more.

toggle_ephemeralB

Set disappearing messages for a group (expiration in seconds: 0, 86400, 604800 or 7776000).

Inputs: groupJid (required), expiration (required), instanceName (required).

update_block_statusC

Block or unblock a contact.

Inputs: number (required), status (required), instanceName (required).

update_group_descriptionC

Change a group's description.

Inputs: groupJid (required), description (required), instanceName (required).

update_group_pictureB

Change a group's picture (URL or base64).

Inputs: image (required), groupJid (required), instanceName (required).

update_group_settingA

Change group settings: who can send messages (announcement) or edit group info (locked).

Inputs: action (required), groupJid (required), instanceName (required).

update_group_subjectC

Change a group's subject (name).

Inputs: subject (required), groupJid (required), instanceName (required).

update_messageB

Edit a previously sent text message.

Inputs: key (required), text (required), number (required), instanceName (required).

update_participantA

Add, remove, promote (to admin) or demote participants in a group.

Inputs: action (required), groupJid (required), instanceName (required), participants (required).

update_privacy_settingsB

Update the privacy settings of the instance (read receipts, profile, status, online, last seen, group add).

Inputs: instanceName (required), last, online, status, +3 more.

update_profile_nameA

Update the display name of the instance's own profile.

Inputs: name (required), instanceName (required).

update_profile_pictureA

Update the profile picture of the instance (URL or base64).

Inputs: picture (required), instanceName (required).

update_profile_statusB

Update the 'about'/status text of the instance's own profile.

Inputs: status (required), instanceName (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

C2.9/5.0

Scored 2026-06-30 03:20 across 70 tools

Disambiguation4/5

Each tool targets a distinct action, but there is some overlap between send_media (which can send audio) and send_whatsapp_audio (voice note), and between send_media and send_ptv (round video). Agents may occasionally misselect between these. Overall, most tools have clear boundaries.

Naming Consistency3/5

Naming follows snake_case but uses a mix of verbs: get, fetch, find for retrieval; send, update, set for actions. Inconsistencies like get_connection_state vs fetch_profile, and send_chat_presence vs set_evolution_presence reduce predictability.

Tool Count2/5

70 tools is excessive for a typical MCP server. While each tool serves a specific purpose, the high number makes the surface unwieldy and increases selection difficulty. A consolidated API with fewer but more flexible tools would improve coherence.

Completeness5/5

The tool set covers nearly all WhatsApp operations: instance lifecycle, messaging (text, media, reactions, polls, templates, status), group management (create, update, invite, participants), profile, privacy, and webhooks. Only minor gaps like deleting a chat or forwarding messages exist, making it very complete for its domain.

Maintenance

ActivityInactive

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

uni-msg WhatsApp
com.uni-msg
Drive WhatsApp from any MCP client: pair devices, send text and media, manage contacts and groups.
Communication App Automation
1
https://uni-msg.com/mcp
whatsappB
me.wacli
Your own WhatsApp as an MCP server: read, search and send from any MCP client.
Communication App Automation
1313
https://wacli.me/mcp
Blueticks WhatsApp MCP
co.blueticks
WhatsApp MCP on your own number: read chats, search contacts, send messages.
Communication App Automation
1
https://api.blueticks.co/mcp
whatsapp
io.2chat
WhatsApp (Web + Business API), SMS, contacts, and call records via 2Chat's MCP server.
Communication CRM
1
https://mcp.2chat.io/mcp

Related MCP Servers

mcp-evolution
Communication Social Media
billyfranklim1
A
license
B
quality
C
maintenance
MCP server that integrates Evolution API to enable WhatsApp messaging, chat management, group operations, and instance control through natural language tools.
Updated 2 months ago (2026-09-29 01:02 UTC)
54
41 npm
1
MIT
mcp-evolution-api
Communication Customer Support
pauloFroes
A
license
A
quality
D
maintenance
MCP server that wraps the Evolution API (WhatsApp) as semantic tools for LLM agents, enabling messaging, chat management, group operations, and instance control via natural language.
Updated 8 months ago (2026-03-02 17:10 UTC)
32
MIT
Evolution MCP Server
Communication Developer Tools
MatheusLarcher
F
license
Not graded
quality
D
maintenance
MCP server for managing WhatsApp instances and sending messages through Evolution API.
Updated a year ago (2025-10-08 13:02 UTC)
1
-
evolution-api-mcp-server
Communication Social Media
Floryvibla
A
license
B
quality
D
maintenance
Enables WhatsApp messaging and management through the Evolution API, supporting sending texts, checking numbers, listing contacts and groups, and more.
Updated 5 months ago (2026-06-29 13:03 UTC)
25
MIT

MCP-WHATSAPP-EVO

Tools

Setup

Use with Claude Code

Use with other MCP clients

Notes on phone numbers & JIDs

Security

Architecture

License

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

mcp-evolution

mcp-evolution-api

Evolution MCP Server

evolution-api-mcp-server