Mcp Evolution Api

io.github.codesparPublished by GitHub account codesparv0.2.2Updated Oct 24, 2026

MCP server for Evolution API — WhatsApp messaging, instances, contacts

VerifiedSTDIODesktop onlyProductivity & WorkflowCommunication & Collaboration

Overview

AI-generated overview

Local MCP server that connects an assistant to a self-hosted Evolution API instance to send WhatsApp messages and manage instances, contacts and groups.

What you can do
Send WhatsApp text, image, document and poll messages, and mark messages as read or delete them for me or for everyone. List, create, restart, logout or delete WhatsApp instances, get pairing QR codes and check connection state. Read contacts, chat history and messages, and check whether a phone number is registered on WhatsApp. Create groups, read group metadata, fetch invite codes, leave groups and add, remove, promote or demote participants. Update instance profile details, set presence and archive or unarchive chats.
When to use it
Useful when you run your own Evolution API instance and want an assistant to draft and send WhatsApp messages, look up chats and contacts, or administer WhatsApp instances and groups from a chat session.
Requirements
Runs locally via npx (Node.js). Needs a reachable self-hosted Evolution API instance, set through the EVOLUTION_API_URL environment variable, and an API key in EVOLUTION_API_KEY. The README recommends deploying the instance with Docker for testing.
Before you install
The server can send messages and polls to real WhatsApp contacts, create and delete instances, change group membership and delete messages for everyone; these actions are hard to undo. It holds an API key that grants control of the WhatsApp instance, so keep it out of shared configs. Message content and contact data pass through your Evolution API instance.

Installation

In SourceWeft

  1. Open Mcp Evolution Api in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

@codespar/mcp-evolution-api

MCP server for Evolution API — self-hosted WhatsApp messaging API

[npm] [License: MIT]

Quick Start

Claude Desktop

Add to ~/.config/claude/claude_desktop_config.json:

json
{  "mcpServers": {    "evolution-api": {      "command": "npx",      "args": ["-y", "@codespar/mcp-evolution-api"],      "env": {        "EVOLUTION_API_URL": "https://your-instance.example.com",        "EVOLUTION_API_KEY": "your-key"      }    }  }}

Claude Code

bash
claude mcp add evolution-api -- npx @codespar/mcp-evolution-api

Cursor / VS Code

Add to .cursor/mcp.json or .vscode/mcp.json:

json
{  "servers": {    "evolution-api": {      "command": "npx",      "args": ["-y", "@codespar/mcp-evolution-api"],      "env": {        "EVOLUTION_API_URL": "https://your-instance.example.com",        "EVOLUTION_API_KEY": "your-key"      }    }  }}

Tools (25)

ToolPurpose
send_textSend a text message via WhatsApp
send_imageSend an image message via WhatsApp
send_documentSend a document via WhatsApp
get_instancesList all WhatsApp instances
create_instanceCreate a new WhatsApp instance
get_qrcodeGet QR code for instance pairing
get_contactsGet contacts from an instance
send_pollSend a poll message via WhatsApp
get_messagesGet messages from a chat
check_numberCheck if a phone number is registered on WhatsApp
create_groupCreate a WhatsApp group
get_group_infoGet group metadata, participants, and settings
update_profileUpdate instance profile (name, status text, or picture)
set_presenceSet online/offline presence for an instance
get_chat_historyGet full chat history with pagination support
logout_instanceLogout an instance (disconnects the WhatsApp session without deleting the instance)
restart_instanceRestart an instance
delete_instanceDelete an instance permanently
connection_stateGet the connection state of an instance (open, connecting, close)
leave_groupLeave a WhatsApp group
update_group_participantsAdd, remove, promote, or demote participants in a WhatsApp group
fetch_group_invite_codeFetch the invite code/link for a WhatsApp group
mark_message_as_readMark one or more messages in a chat as read
archive_chatArchive or unarchive a chat
delete_messageDelete a message for me or for everyone in a chat

Authentication

Evolution API uses an API key passed via the apikey header.

Sandbox / Testing

Evolution API is self-hosted. Deploy your own instance using Docker for testing.

Get your credentials

  1. Go to Evolution API Documentation
  2. Deploy your own instance (Docker recommended)
  3. Get the API key from your instance configuration
  4. Set the environment variables

Environment Variables

VariableRequiredDescription
EVOLUTION_API_URLYesBase URL of your Evolution API instance
EVOLUTION_API_KEYYesAPI key for authentication

Roadmap

v0.2 (planned)

  • create_group — Create a WhatsApp group
  • get_group_info — Get group details and participants
  • update_profile — Update instance profile (name, photo, status)
  • set_presence — Set online/offline presence status
  • get_chat_history — Get full chat history with a contact

v0.3 (planned)

  • bulk_send — Send messages to multiple contacts
  • template_messages — Send WhatsApp Business template messages
  • label_management — Create, update, and assign labels to chats

Want to contribute? Open a PR or request a tool.

Links

Enterprise

Need governance, budget limits, and audit trails for agent payments? CodeSpar Enterprise adds policy engine, payment routing, and compliance templates on top of these MCP servers.

License

MIT

Source: packages/communication/evolution-api/README.md at commit d0a519a

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.2.2LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts