Skip to main content
Glama
mcp-evolution-api

mcp-evolution-api

by pauloFroes

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

EVOLUTION_BASE_URL

Base URL of your Evolution API instance

EVOLUTION_API_KEY

API key for authentication

EVOLUTION_INSTANCE

Instance name (e.g. whatsapp-paulo)

Related MCP server: WA MCP

Installation

Claude Code

Three installation scopes are available:

Scope

Flag

Config file

Use case

local

-s local

.mcp.json

This project only (default)

project

-s project

.claude/mcp.json

Shared with team via git

user

-s user

~/.claude/mcp.json

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-api

Replace -s user with -s local or -s project as 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_contact

Block or unblock a contact

send_audio

Send audio/voice note

send_contact

Send contact card (vCard)

send_location

Send location pin

send_media

Send image, video, or document

send_poll

Send a poll

send_reaction

React to a message with emoji

send_sticker

Send a sticker

send_text

Send a text message

Chat (12)

Tool

Description

archive_chat

Archive or unarchive a chat

check_whatsapp_numbers

Verify if numbers exist on WhatsApp

delete_message

Delete a message for everyone

fetch_profile

Fetch contact profile information

fetch_profile_picture

Get contact profile picture URL

find_chats

List all chats/conversations

find_contacts

Search WhatsApp contacts

find_messages

Retrieve messages from a chat

get_base64_from_media

Extract media as base64 from a message

mark_as_read

Mark messages as read

send_presence

Send typing/recording indicator

update_message

Edit a previously sent message

Groups (10)

Tool

Description

create_group

Create a new group

fetch_invite_code

Get group invite link

find_group

Get group info by JID

group_participants

List group members

leave_group

Leave a group

list_groups

List all groups

send_group_invite

Send group invite to numbers

update_group_description

Update group description

update_group_picture

Update group profile picture

update_group_subject

Update group name

Instance (1)

Tool

Description

check_connection

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 tools
archive_chatArchive ChatB

Archive or unarchive a WhatsApp chat.

Inputs: archive (required), remote_jid (required).

block_contactBlock/Unblock ContactA
Destructive

Block or unblock a WhatsApp contact. Blocking prevents the contact from sending you messages.

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

check_connectionCheck ConnectionA
Read-only

Check the connection status of the WhatsApp instance. Returns state (open/close/connecting).

Inputs: no named parameters.

check_whatsapp_numbersCheck WhatsApp NumbersA
Read-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 MessageA
Destructive

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 CodeA
Read-only

Get the invite link/code for a WhatsApp group. Requires admin privileges.

Inputs: group_jid (required).

fetch_profileFetch ProfileA
Read-only

Fetch the WhatsApp profile information of a contact (name, status, etc.).

Inputs: number (required).

fetch_profile_pictureFetch Profile PictureB
Read-only

Get the profile picture URL of a WhatsApp contact.

Inputs: number (required).

find_chatsFind ChatsA
Read-only

List all WhatsApp chats/conversations. Returns chat metadata including last message, unread count, etc.

Inputs: no named parameters.

find_contactsFind ContactsA
Read-only

Search WhatsApp contacts. Returns all contacts if no filter is provided, or a specific contact by JID.

Inputs: filter_id.

find_groupFind GroupA
Read-only

Get detailed information about a specific WhatsApp group by JID.

Inputs: group_jid (required).

find_messagesFind MessagesA
Read-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 MessageA
Read-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 ParticipantsA
Read-only

List all members/participants of a specific WhatsApp group.

Inputs: group_jid (required).

leave_groupLeave GroupA
Destructive

Leave a WhatsApp group. This action is irreversible — you will need a new invite to rejoin.

Inputs: group_jid (required).

list_groupsList GroupsA
Read-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

    A3.5/5.0

    Scored across 32 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • 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.
      54
      41 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      WhatsApp MCP server that exposes messaging, groups, contacts, and profile management as tools and resources for AI agents, supporting Baileys and Meta Cloud API.
      79 npm
      29
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      MCP 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.
      11
      16 npm
      MIT