Evolution API MCP

用于直接从 Claude Code 发送和接收 WhatsApp 消息的 MCP 服务器，使用 Evolution API（开源，自托管）。

功能

• 创建和管理 WhatsApp 实例

• 发送文本、媒体、音频、位置、联系人、投票、贴纸、按钮和列表消息

• 读取对话和接收到的消息

• 对消息做出反应、归档聊天、标记为已读

Related MCP server: mcp-evolution

前置要求

• Docker Desktop

• Python 3.11+

• uv (Python 包管理器)

• Claude Code

安装

1. 启动 Evolution API

git clone https://github.com/SEU_USUARIO/evolution-api-mcp.git
cd evolution-api-mcp
docker compose up -d

等待约 15 秒并进行测试：

curl http://localhost:8080/

应该返回 {"status":200,"message":"Welcome to the Evolution API, it is working!"}。

2. 安装 MCP 服务器

uv venv
uv pip install -e .

3. 在 Claude Code 中注册

claude mcp add evolution-api -s user -- evolution-api-mcp

或者手动添加到 ~/.claude.json 文件中：

{
  "mcpServers": {
    "evolution-api": {
      "type": "stdio",
      "command": "evolution-api-mcp",
      "env": {
        "EVOLUTION_API_URL": "http://localhost:8080",
        "EVOLUTION_API_KEY": "evo_mcp_2024"
      }
    }
  }
}

Windows: 命令可能需要使用 .exe 的完整路径： C:/Users/您的用户名/evolution-api-mcp/.venv/Scripts/evolution-api-mcp.exe

4. 连接您的 WhatsApp

1. 在浏览器中打开 http://localhost:8080/manager/

2. 使用全局 API 密钥：evo_mcp_2024

3. 创建一个实例（例如："meuwhats"）

4. 点击 "生成二维码"

5. 使用您的 WhatsApp 扫描：设置 > 已连接的设备 > 连接设备

5. 使用！

重新打开 Claude Code 并开始使用：

> envia uma mensagem pro 5511999999999 dizendo oi
> mostra minhas conversas recentes
> envia uma foto pra fulano

配置

Docker Compose 的默认 API 密钥是 evo_mcp_2024。如果需要，请在 docker-compose.yml 中更改。

结构

evolution-api-mcp/
├── docker-compose.yml          # Evolution API + PostgreSQL
├── pyproject.toml               # Dependencias Python
└── src/evolution_api_mcp/
    ├── server.py                # MCP server (FastMCP + CodeMode)
    ├── client.py                # HTTP client async
    └── tools/
        ├── instance.py          # Criar/conectar/deletar instancias
        ├── messages.py          # Enviar texto, midia, audio, etc.
        └── chat.py              # Listar chats, ler mensagens

可用工具

实例 (Instance)

• create_instance - 创建 WhatsApp 实例

• connect_instance - 连接并生成二维码

• fetch_instances - 列出实例

• connection_state - 检查连接状态

• logout_instance - 断开 WhatsApp 连接

• restart_instance - 重启实例

• delete_instance - 删除实例

消息 (Messages)

• send_text - 发送文本

• send_media - 发送图片、视频或文档

• send_audio - 发送音频/语音笔记

• send_location - 发送位置

• send_contact - 发送联系人名片

• send_reaction - 使用表情符号做出反应

• send_poll - 发送投票

• send_buttons - 发送交互式按钮

• send_list - 发送交互式列表

• send_sticker - 发送贴纸

聊天 (Chat)

• find_chats - 列出对话

• find_messages - 读取聊天中的消息

• archive_chat - 归档/取消归档聊天

• mark_message_as_read - 标记为已读

许可证

MIT