# 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.