This project implements an MCP (Model Context Protocol) server that exposes all Evolution API v2 functionalities to language models.

The server exposes all Evolution API feature categories:

• API and instance status verification
• Instance creation, deletion, and restart
• Presence management
• Logout

• Text messages
• Messages with media (images, documents, videos, audios)
• Stickers
• Location
• Contacts
• Polls and lists
• Status

• WhatsApp number verification
• Mark messages as read
• Archive conversations
• Delete messages
• Chat presence management
• Search for messages and contacts

• Search and update profile information
• Update profile picture
• Privacy settings

• Group creation and management
• Add/remove participants
• Configure ephemeral messages
• Group invites

• Typebot
• Chatwoot

• Node.js 18+
• NPM or Yarn
• Access to an Evolution API v2 server

# Install locally
git clone https://github.com/IntuitivePhella/mcp-evolution-api.git
cd mcp-evolution-api
npm install
npm run build

# Run directly via npx (when published)
npx mcp-evolution-api

# Build the image
docker build -t mcp-evolution-api .

# Run the container
docker run -p 3000:3000 --env-file .env mcp-evolution-api

Create a .env file in the project root with the following variables:

# Evolution API server URL
EVOLUTION_API_URL=https://your-evolution-api-server.com

# Evolution API key
EVOLUTION_API_KEY=your-api-key

# WhatsApp instance ID in Evolution API
EVOLUTION_API_INSTANCE=default-instance

# Enable WebSocket server (optional)
ENABLE_WEBSOCKET=true

# Port for WebSocket server (optional)
PORT=3000

To start the server in development mode:

npm run dev

To compile and run in production:

npm run build
npm start

# Using npm scripts
npm run docker:build
npm run docker:run

This MCP server supports two connection methods:

Used primarily for local connections and integration with tools like Claude Desktop.

Ideal for remote connections or when the server is in a Docker container. To enable:

ENABLE_WEBSOCKET=true
PORT=3000 # optional port, default is 3000

Add to your claude_desktop_config.json file:

{
  "mcpServers": {
    "evolution-api": {
      "command": "node",
      "args": [
        "/full/path/to/mcp-evolution-api/dist/index.js"
      ],
      "env": {
        "EVOLUTION_API_URL": "https://your-evolution-api-server.com",
        "EVOLUTION_API_KEY": "your-api-key",
        "EVOLUTION_API_INSTANCE": "your-instance"
      }
    }
  }
}

See a complete example at examples/claude_desktop_config.json.

To configure in n8n, see the detailed guide at examples/n8n_config.md.

The MCP server exposes the following tools that can be called by the MCP client:

• getApiStatus: Check Evolution API status

• getInstanceStatus: Check WhatsApp connection status
• setPresence: Set presence status
• logoutInstance: Disconnect the instance
• restartInstance: Restart the instance

• sendTextMessage: Send a text message
• sendMedia: Send media (image, document, video, audio)
• sendAudio: Send audio/voice message
• sendSticker: Send a sticker
• sendLocation: Send a location
• sendContact: Send a contact
• sendPoll: Send a poll

• checkWhatsAppNumber: Check if a number is on WhatsApp
• markMessageAsRead: Mark message as read
• archiveChat: Archive/unarchive a chat
• deleteMessageForEveryone: Delete message for everyone

• updateProfileName: Update profile name
• updateProfileStatus: Update profile status

• createGroup: Create a new group
• addGroupParticipants: Add participants to a group

The MCP server provides the following resources:

• contacts://list: List all available contacts
• chats://list: List all available conversations
• groups://list: List all available groups
• profile://info: Display profile information
• privacy://settings: Display privacy settings

import { McpClient } from "@modelcontextprotocol/sdk/client/mcp.js";

// Connect to the MCP server
const client = new McpClient();
await client.connect(mcpServerTransport);

// Check API status
const status = await client.callTool("getApiStatus", {});
console.log(status.content[0].text);

// Send a message
const msgResult = await client.callTool("sendTextMessage", {
  number: "5511999999999",
  text: "Hello, this is a test message!"
});
console.log(msgResult.content[0].text);

// Send media
const mediaResult = await client.callTool("sendMedia", {
  number: "5511999999999",
  url: "https://example.com/image.jpg",
  caption: "Check out this image!",
  mediaType: "image"
});
console.log(mediaResult.content[0].text);

// Load resources
const groups = await client.loadResource("groups://list");
console.log(groups.contents[0].text);

MIT