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)

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