MCP Evolution API

MCP Evolution API

适用于 Claude 的模型上下文协议（MCP）服务，可与 Evolution API 集成，实现 WhatsApp 自动化。

概览

此 MCP 服务允许 Claude 通过 Evolution API 与 WhatsApp 交互，实现以下功能：

• 管理 WhatsApp 实例
• 发送各种类型的消息
• 处理联系人和群组
• 配置 Webhook 和设置

📂 项目结构

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

🚀 快速设置

环境设置

创建 .env 文件并填入 Evolution API 凭据：

EVOLUTION_API_URL=https://evo-api.decisao.ai/
EVOLUTION_API_KEY=REPLACE_WITH_YOUR_REAL_KEY

注意：你提供了 API URL 和密钥。为确保安全，切勿将真实 API 密钥提交到代码库或公开分享。在本地使用 .env 文件，或在生产环境中使用密钥管理器。

📋 部署选项

环境	步骤	命令
本地开发	1. 克隆并安装 2. 在开发模式下运行	git clone https://github.com/aiteks-ltda/mcp-evo-api.git && cd mcp-evo-api && bun install bun run dev
本地生产	1. 克隆并安装 2. 构建并运行	git clone https://github.com/aiteks-ltda/mcp-evo-api.git && cd mcp-evo-api && bun install bun run build && bun run dist/main.js
Docker Compose	使用 Docker Compose 运行	git clone https://github.com/aiteks-ltda/mcp-evo-api.git && cd mcp-evo-api docker-compose up -d
Docker	构建并运行容器	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 配置

将以下内容添加到 Claude Desktop 配置文件中（通常位于 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "evo-api": {
      "command": "node",
      "args": [
        "/path/to/your/mcp-evo-api/dist/main.js"
      ]
    }
  }
}

如果使用 Docker 部署：

{
  "mcpServers": {
    "evo-api": {
      "url": "http://localhost:3000"
    }
  }
}

📊 实现状态

类别	已实现	待实现
核心 API	✅ 获取信息 ✅ 创建实例 ✅ 获取实例列表 ✅ 连接实例 ✅ 重启实例 ✅ 连接状态 ✅ 登出实例 ✅ 删除实例 ✅ 设置在线状态	❌ 检查是否为 WhatsApp
Webhook 和设置	✅ 设置 Webhook ✅ 查找 Webhook ✅ 设置配置 ✅ 查找配置
消息	✅ 发送纯文本 ✅ 发送状态 ✅ 发送媒体 ✅ 发送 WhatsApp 音频 ✅ 发送贴纸 ✅ 发送位置 ✅ 发送联系人 ✅ 发送回应 ✅ 发送投票 ✅ 发送列表 ✅ 发送按钮	❌ 将消息标记为已读 ❌ 将消息标记为未读 ❌ 归档聊天 ❌ 为所有人删除消息 ❌ 更新消息 ❌ 发送在线状态（聊天控制）
聊天和联系人	✅ 查找联系人 ✅ 查找聊天	❌ 更新屏蔽状态 ❌ 获取个人资料图片 URL ❌ 获取 Base64 ❌ 查找消息 ❌ 查找状态消息
群组	✅ 按 JID 查找群组 ✅ 获取所有群组 ✅ 查找群组成员	❌ 创建群组 ❌ 更新群组图片 ❌ 更新群组主题 ❌ 更新群组描述 ❌ 获取邀请代码 ❌ 撤销邀请代码 ❌ 发送群组邀请 ❌ 按邀请代码查找群组 ❌ 更新群组成员 ❌ 更新群组设置 ❌ 切换临时消息 ❌ 离开群组
个人资料设置		❌ 获取商家资料 ❌ 获取个人资料 ❌ 更新个人资料名称 ❌ 更新个人资料状态 ❌ 更新个人资料图片 ❌ 移除个人资料图片 ❌ 获取隐私设置 ❌ 更新隐私设置
机器人集成		❌ Typebot 集成 ❌ OpenAI 集成 ❌ Evolution Bot ❌ Dify Bot ❌ Flowise Bot
其他集成		❌ Chatwoot ❌ Websocket ❌ SQS ❌ RabbitMQ

如需了解更多信息，请参阅 Evolution API 文档。

示例

• examples/hono-bun/ - 用于 Bun 的小型 Hono 服务（已保存的示例）。运行说明请参阅 examples/hono-bun/README.md。