Content
# MCP Evolution API
A Model Context Protocol (MCP) server for Claude that integrates with [Evolution API](https://doc.evolution-api.com/) for WhatsApp automation.
## Overview
This MCP server allows Claude to interact with WhatsApp through the Evolution API, enabling capabilities like:
- Managing WhatsApp instances
- Sending various types of messages
- Working with contacts and groups
- Configuring webhooks and settings
## 📂 Project Structure
```
mcp-evo-api/
├── src/
│ ├── tools/ # MCP tools implementation for Evolution API
│ ├── utils/ # Shared utilities, including Evolution API client
│ ├── main.ts # Server entry point
│ └── types.ts # Shared type definitions
├── scripts/ # Helper scripts
├── biome.json # Linting configuration
├── tsconfig.json # TypeScript configuration
├── docker-compose.yml # Docker Compose configuration
├── Dockerfile # Docker build configuration
└── package.json # Project dependencies
```
## 🚀 Quick Setup
### Environment Setup
Create a `.env` file with your Evolution API credentials:
```
EVOLUTION_API_URL=https://evo-api.decisao.ai/
EVOLUTION_API_KEY=REPLACE_WITH_YOUR_REAL_KEY
```
Note: you provided the API URL and a key. For security, never commit real API keys to the repository or share them publicly. Use a local `.env` file or a secrets manager in production.
### 📋 Deployment Options
| Environment | Steps | Command |
|-------------|-------|---------|
| **Local Development** | 1. Clone and install<br>2. Run in dev mode | `git clone https://github.com/aiteks-ltda/mcp-evo-api.git && cd mcp-evo-api && bun install`<br>`bun run dev` |
| **Local Production** | 1. Clone and install<br>2. Build and run | `git clone https://github.com/aiteks-ltda/mcp-evo-api.git && cd mcp-evo-api && bun install`<br>`bun run build && bun run dist/main.js` |
| **Docker Compose** | Run with Docker Compose | `git clone https://github.com/aiteks-ltda/mcp-evo-api.git && cd mcp-evo-api`<br>`docker-compose up -d` |
| **Docker** | Build and run container | `docker run -d -p 3000:3000 -e EVOLUTION_API_URL=yoururl -e EVOLUTION_API_KEY=yourkey --name mcp-evo-api ghcr.io/aiteks-ltda/mcp-evo-api:latest` |
### Claude Desktop Configuration
Add this to your Claude Desktop config file (typically located at `~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"evo-api": {
"command": "node",
"args": [
"/path/to/your/mcp-evo-api/dist/main.js"
]
}
}
}
```
If using the Docker deployment:
```json
{
"mcpServers": {
"evo-api": {
"url": "http://localhost:3000"
}
}
}
```
## 📊 Implementation Status
| Category | Implemented | Pending Implementation |
|----------|-------------|------------------------|
| **Core API** | ✅ Get Information<br>✅ Create Instance<br>✅ Fetch Instances<br>✅ Instance Connect<br>✅ Restart Instance<br>✅ Connection State<br>✅ Logout Instance<br>✅ Delete Instance<br>✅ Set Presence | ❌ Check is WhatsApp |
| **Webhook & Settings** | ✅ Set Webhook<br>✅ Find Webhook<br>✅ Set Settings<br>✅ Find Settings | |
| **Messaging** | ✅ Send Plain Text<br>✅ Send Status<br>✅ Send Media<br>✅ Send WhatsApp Audio<br>✅ Send Sticker<br>✅ Send Location<br>✅ Send Contact<br>✅ Send Reaction<br>✅ Send Poll<br>✅ Send List<br>✅ Send Buttons | ❌ Mark Message As Read<br>❌ Mark Message As Unread<br>❌ Archive Chat<br>❌ Delete Message for Everyone<br>❌ Update Message<br>❌ Send Presence (Chat Ctrl) |
| **Chat & Contacts** | ✅ Find Contacts<br>✅ Find Chats | ❌ Update Block Status<br>❌ Fetch Profile Picture URL<br>❌ Get Base64<br>❌ Find Messages<br>❌ Find Status Message |
| **Groups** | ✅ Find Group by JID<br>✅ Fetch All Groups<br>✅ Find Group Members | ❌ Create Group<br>❌ Update Group Picture<br>❌ Update Group Subject<br>❌ Update Group Description<br>❌ Fetch Invite Code<br>❌ Revoke Invite Code<br>❌ Send Group Invite<br>❌ Find Group by Invite Code<br>❌ Update Group Members<br>❌ Update Group Setting<br>❌ Toggle Ephemeral<br>❌ Leave Group |
| **Profile Settings** | | ❌ Fetch Business Profile<br>❌ Fetch Profile<br>❌ Update Profile Name<br>❌ Update Profile Status<br>❌ Update Profile Picture<br>❌ Remove Profile Picture<br>❌ Fetch Privacy Settings<br>❌ Update Privacy Settings |
| **Bot Integrations** | | ❌ Typebot Integrations<br>❌ OpenAI Integrations<br>❌ Evolution Bot<br>❌ Dify Bot<br>❌ Flowise Bot |
| **Other Integrations** | | ❌ Chatwoot<br>❌ Websocket<br>❌ SQS<br>❌ RabbitMQ |
For more information, refer to the [Evolution API Documentation](https://doc.evolution-api.com/).
## Examples
- `examples/hono-bun/` - pequeno servidor Hono para Bun (exemplo salvo). Veja `examples/hono-bun/README.md` para instruções de execução.
