mcp-evolution-api
Provides tools for WhatsApp messaging, chat management, group operations, and instance management via the Evolution API. Allows sending text, media, location, polls, and more; managing chats and groups; checking connection status; and other WhatsApp operations.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-evolution-api send a text message to +1234567890 saying 'Hello from MCP!'"
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-evolution-api
MCP server that wraps the Evolution API (WhatsApp) as semantic tools for LLM agents.
Works with Claude Code, Codex, Claude Desktop, Cursor, VS Code, Windsurf, and any MCP-compatible client.
Prerequisites
Node.js 18+
Evolution API instance running (docs)
Variable | Description |
| Base URL of your Evolution API instance |
| API key for authentication |
| Instance name (e.g. |
Related MCP server: WA MCP
Installation
Claude Code
Three installation scopes are available:
Scope | Flag | Config file | Use case |
local |
|
| This project only (default) |
project |
|
| Shared with team via git |
user |
|
| All your projects |
claude mcp add evolution-api -s user \
-e EVOLUTION_BASE_URL=https://your-instance.example.com \
-e EVOLUTION_API_KEY=your-key \
-e EVOLUTION_INSTANCE=your-instance \
-- npx -y github:pauloFroes/mcp-evolution-apiReplace
-s userwith-s localor-s projectas needed.
Codex
Add to your Codex configuration:
[mcp_servers.evolution-api]
command = "npx"
args = ["-y", "github:pauloFroes/mcp-evolution-api"]
env_vars = ["EVOLUTION_BASE_URL", "EVOLUTION_API_KEY", "EVOLUTION_INSTANCE"]Claude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"evolution-api": {
"command": "npx",
"args": ["-y", "github:pauloFroes/mcp-evolution-api"],
"env": {
"EVOLUTION_BASE_URL": "https://your-instance.example.com",
"EVOLUTION_API_KEY": "your-key",
"EVOLUTION_INSTANCE": "your-instance"
}
}
}
}Cursor
Add to ~/.cursor/mcp.json:
{
"mcpServers": {
"evolution-api": {
"command": "npx",
"args": ["-y", "github:pauloFroes/mcp-evolution-api"],
"env": {
"EVOLUTION_BASE_URL": "https://your-instance.example.com",
"EVOLUTION_API_KEY": "your-key",
"EVOLUTION_INSTANCE": "your-instance"
}
}
}
}VS Code
Add to .vscode/mcp.json in your project:
{
"servers": {
"evolution-api": {
"command": "npx",
"args": ["-y", "github:pauloFroes/mcp-evolution-api"],
"env": {
"EVOLUTION_BASE_URL": "https://your-instance.example.com",
"EVOLUTION_API_KEY": "your-key",
"EVOLUTION_INSTANCE": "your-instance"
}
}
}
}Windsurf
Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"evolution-api": {
"command": "npx",
"args": ["-y", "github:pauloFroes/mcp-evolution-api"],
"env": {
"EVOLUTION_BASE_URL": "https://your-instance.example.com",
"EVOLUTION_API_KEY": "your-key",
"EVOLUTION_INSTANCE": "your-instance"
}
}
}
}Available Tools
Messaging (9)
Tool | Description |
| Block or unblock a contact |
| Send audio/voice note |
| Send contact card (vCard) |
| Send location pin |
| Send image, video, or document |
| Send a poll |
| React to a message with emoji |
| Send a sticker |
| Send a text message |
Chat (12)
Tool | Description |
| Archive or unarchive a chat |
| Verify if numbers exist on WhatsApp |
| Delete a message for everyone |
| Fetch contact profile information |
| Get contact profile picture URL |
| List all chats/conversations |
| Search WhatsApp contacts |
| Retrieve messages from a chat |
| Extract media as base64 from a message |
| Mark messages as read |
| Send typing/recording indicator |
| Edit a previously sent message |
Groups (10)
Tool | Description |
| Create a new group |
| Get group invite link |
| Get group info by JID |
| List group members |
| Leave a group |
| List all groups |
| Send group invite to numbers |
| Update group description |
| Update group profile picture |
| Update group name |
Instance (1)
Tool | Description |
| Check WhatsApp connection status |
Authentication
All requests use the apikey header. The instance name is automatically appended to API endpoint paths. Environment variables are validated at startup — the server fails fast if any are missing.
License
MIT
Available Tools
32 toolsarchive_chatArchive ChatB
Archive or unarchive a WhatsApp chat.
Inputs: archive (required), remote_jid (required).
block_contactBlock/Unblock ContactADestructive
Block or unblock a WhatsApp contact. Blocking prevents the contact from sending you messages.
Inputs: number (required), status (required).
check_connectionCheck ConnectionARead-only
Check the connection status of the WhatsApp instance. Returns state (open/close/connecting).
Inputs: no named parameters.
check_whatsapp_numbersCheck WhatsApp NumbersARead-only
Verify if phone numbers are registered on WhatsApp. Returns which numbers exist and their JIDs.
Inputs: numbers (required).
create_groupCreate GroupA
Create a new WhatsApp group with specified participants.
Inputs: subject (required), participants (required), description.
delete_messageDelete MessageADestructive
Delete a WhatsApp message for everyone in the chat. Only works for messages you sent within the time limit.
Inputs: from_me (required), message_id (required), remote_jid (required).
fetch_invite_codeFetch Invite CodeARead-only
Get the invite link/code for a WhatsApp group. Requires admin privileges.
Inputs: group_jid (required).
fetch_profileFetch ProfileARead-only
Fetch the WhatsApp profile information of a contact (name, status, etc.).
Inputs: number (required).
fetch_profile_pictureFetch Profile PictureBRead-only
Get the profile picture URL of a WhatsApp contact.
Inputs: number (required).
find_chatsFind ChatsARead-only
List all WhatsApp chats/conversations. Returns chat metadata including last message, unread count, etc.
Inputs: no named parameters.
find_contactsFind ContactsARead-only
Search WhatsApp contacts. Returns all contacts if no filter is provided, or a specific contact by JID.
Inputs: filter_id.
find_groupFind GroupARead-only
Get detailed information about a specific WhatsApp group by JID.
Inputs: group_jid (required).
find_messagesFind MessagesARead-only
Retrieve messages from a specific WhatsApp chat. Returns recent messages ordered by timestamp.
Inputs: remote_jid (required), limit.
get_base64_from_mediaGet Base64 from Media MessageARead-only
Extract media content as base64 from a WhatsApp message. Use this instead of temporary media URLs which expire quickly. Pass the message key ID from find_messages results.
Inputs: message_id (required), convert_to_mp4.
group_participantsGroup ParticipantsARead-only
List all members/participants of a specific WhatsApp group.
Inputs: group_jid (required).
leave_groupLeave GroupADestructive
Leave a WhatsApp group. This action is irreversible — you will need a new invite to rejoin.
Inputs: group_jid (required).
list_groupsList GroupsARead-only
List all WhatsApp groups the connected number participates in.
Inputs: get_participants.
mark_as_readMark Messages as ReadA
Mark specific messages as read in a WhatsApp chat.
Inputs: remote_jid (required), message_ids (required).
send_audioSend Audio MessageA
Send a WhatsApp audio message (voice note). Audio URL must be publicly accessible.
Inputs: number (required), audio_url (required), delay.
send_contactSend Contact CardA
Send a WhatsApp contact card (vCard) to a phone number.
Inputs: number (required), contact_name (required), contact_phone (required), delay.
send_group_inviteSend Group InviteA
Send a group invite link to specified phone numbers via WhatsApp.
Inputs: numbers (required), group_jid (required), description.
send_locationSend LocationB
Send a WhatsApp location pin to a phone number.
Inputs: number (required), latitude (required), longitude (required), name, +2 more.
send_mediaSend Media MessageA
Send a WhatsApp media message (image, video, or document). Media URL must be publicly accessible.
Inputs: number (required), media_url (required), media_type (required), delay, +2 more.
send_pollSend PollC
Send a WhatsApp poll to a phone number.
Inputs: number (required), options (required), question (required), delay, +1 more.
send_presenceSend PresenceA
Send a presence/typing indicator to a WhatsApp chat (composing, recording, paused, etc.).
Inputs: number (required), presence (required).
send_reactionSend ReactionA
React to a specific WhatsApp message with an emoji.
Inputs: emoji (required), message_id (required), remote_jid (required).
send_stickerSend StickerA
Send a WhatsApp sticker. The sticker URL must be a publicly accessible image (PNG or WebP recommended).
Inputs: number (required), sticker_url (required), delay.
send_textSend Text MessageA
Send a WhatsApp text message to a phone number via Evolution API.
Inputs: text (required), number (required), delay, link_preview.
update_group_descriptionUpdate Group DescriptionA
Update the description of a WhatsApp group. Requires admin privileges.
Inputs: group_jid (required), description (required).
update_group_pictureUpdate Group PictureA
Update the profile picture of a WhatsApp group. Requires admin privileges.
Inputs: group_jid (required), image_url (required).
update_group_subjectUpdate Group SubjectA
Update the name/subject of a WhatsApp group. Requires admin privileges.
Inputs: subject (required), group_jid (required).
update_messageUpdate MessageA
Edit a previously sent WhatsApp message. Only works for your own messages (fromMe: true).
Inputs: text (required), message_id (required), remote_jid (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 32 tools
Most tools have clearly distinct purposes (send_text, send_audio, send_media, etc.), but some ambiguity exists between generic send_media and specific types like send_audio/send_sticker, and find_chats vs list_groups could be confusing. Descriptions mostly resolve these, but not perfectly.
Tools predominantly follow a verb_noun snake_case pattern (send_*, fetch_*, find_*, update_*), but 'group_participants' is a noun phrase without a verb, breaking the otherwise consistent pattern.
With 32 tools, the surface is large and exceeds the typical well-scoped range. Several sending tools could be consolidated (e.g., send_media could cover audio/sticker), and the count feels heavy for the domain.
The set covers sending all message types, chat retrieval, group management, profile access, and connection status. Minor gaps like chat deletion or contact creation exist, but core workflows are well covered and missing features are easily worked around.
Maintenance
Related MCP Connectors
Your own WhatsApp as an MCP server: read, search and send from any MCP client.
Free WhatsApp MCP server for ChatGPT and Claude: read and search chats, every send you approve.
Drive WhatsApp from any MCP client: pair devices, send text and media, manage contacts and groups.
WhatsMCP connects Claude and other MCP-compatible AI agents directly to WhatsApp. Send and receive text, images, documents, and voice notes; manage groups (create, add/remove members, promote admins); look up contacts and profiles; follow channels; and read call and message history — all through a standard MCP interface. For voice use cases, WhatsMCP offers SIP-based calling plans (inbound-only, or full inbound/outbound) so AI voice agents can answer and place WhatsApp calls, plus low-latency WebSocket integrations with voice agent providers like ElevenLabs. Multiple WhatsApp accounts can be paired and managed per workspace, with webhook support for real-time inbound message delivery to your own infrastructure.
Related MCP Servers
- AlicenseBqualityCmaintenanceMCP server that integrates Evolution API to enable WhatsApp messaging, chat management, group operations, and instance control through natural language tools.5441 npm1MIT
- AlicenseNot gradedqualityBmaintenanceWhatsApp MCP server that exposes messaging, groups, contacts, and profile management as tools and resources for AI agents, supporting Baileys and Meta Cloud API.79 npm29MIT
- FlicenseNot gradedqualityDmaintenanceMCP server for managing WhatsApp instances and sending messages through Evolution API.1-
- AlicenseBqualityDmaintenanceMCP server that enables AI agents to operate WhatsApp via Visto Azul API: send text, media, PIX charges, manage campaigns and contacts, and configure webhooks using natural language.1116 npmMIT