Skip to main content
Glama
jppeiro90

MCP-WHATSAPP-EVO

by jppeiro90
OverviewSchemaRelated ServersScoreDiscussions
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-zap

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.

Install Server
A
license - permissive license
C
quality
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jppeiro90/MCP-WHATSAPP-EVO'

If you have feedback or need assistance with the MCP directory API, please join our Discord server