mcp-evolution-api — Claude Code MCP server: WhatsApp via Evolution API
Gives your agent 25 WhatsApp tools backed by your own Evolution API instance: messages, groups, contacts, connection state.
claude mcp add mcp-evolution-api -e EVOLUTION_API_KEY=<EVOLUTION_API_KEY> -- npx -y @codespar/mcp-evolution-apiWhat mcp-evolution-api does
This is a bridge to Evolution API, the self-hosted WhatsApp gateway. Tool calls like send_text, get_contacts or create_group become requests against the instance you run. There is no hosted endpoint to point at, so bringing up Evolution API yourself — Docker is the shortest route — comes first.
Set EVOLUTION_API_URL and EVOLUTION_API_KEY. The key travels in the apikey header; without a working key every call fails auth. Wire the server into your MCP client through npx, or use the dedicated commands for Claude and Codex.
Beyond messaging, the toolset handles instance admin: list, restart, log out, delete, plus chat archiving, read receipts and group participant changes. Bulk sending and WhatsApp Business templates are not in this release — the author lists them for v0.3.
What it helps with
- send a text or image to a WhatsApp chat from the agent
- pull a pairing QR code for a new instance
- verify whether a phone number is on WhatsApp
- add or remove members in a group
- read a chat history page by page
Example prompts for the agent
- Use
check_numberand tell me whether this phone has WhatsApp - Send that text with
send_textand report the delivery status - Get
get_qrcodefor the instance so I can scan it
How to install mcp-evolution-api
Platform CLI
claude mcp add mcp-evolution-api -e EVOLUTION_API_KEY=<EVOLUTION_API_KEY> -- npx -y @codespar/mcp-evolution-apiReplace <…> with your own values
Platform CLI
codex mcp add evolution-api --env EVOLUTION_API_KEY=<EVOLUTION_API_KEY> -- npx -y @codespar/mcp-evolution-apiReplace <…> with your own values
Config file
{
"mcpServers": {
"evolution-api": {
"command": "npx",
"args": [
"-y",
"@codespar/mcp-evolution-api"
],
"env": {
"EVOLUTION_API_KEY": "<EVOLUTION_API_KEY>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"evolution-api": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@codespar/mcp-evolution-api"
],
"env": {
"EVOLUTION_API_KEY": "<EVOLUTION_API_KEY>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e EVOLUTION_API_KEY=<EVOLUTION_API_KEY> evolution-api npx -y @codespar/mcp-evolution-apiReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about mcp-evolution-api
How do I install mcp-evolution-api in Claude Code?
Run claude mcp add mcp-evolution-api -e EVOLUTION_API_KEY=<EVOLUTION_API_KEY> -- npx -y @codespar/mcp-evolution-api with your own key, and make sure the instance URL is configured.
What does mcp-evolution-api do?
It exposes Evolution API methods as MCP tools: sending messages and files, managing instances and groups, reading chats.
What do I need before it works?
A running Evolution API instance of your own and its API key. The server talks to that instance only.
