mcp-evolution-whatsapp-api

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