mcp-evolution-api

@codespar/mcp-evolution-api

Evolution API 的 MCP 服务——可自托管的 WhatsApp 消息 API

快速开始

Claude Desktop

添加到 ~/.config/claude/claude_desktop_config.json：

{
  "mcpServers": {
    "evolution-api": {
      "command": "npx",
      "args": ["-y", "@codespar/mcp-evolution-api"],
      "env": {
        "EVOLUTION_API_URL": "https://your-instance.example.com",
        "EVOLUTION_API_KEY": "your-key"
      }
    }
  }
}

Claude Code

claude mcp add evolution-api -- npx @codespar/mcp-evolution-api

Cursor / VS Code

添加到 .cursor/mcp.json 或 .vscode/mcp.json：

{
  "servers": {
    "evolution-api": {
      "command": "npx",
      "args": ["-y", "@codespar/mcp-evolution-api"],
      "env": {
        "EVOLUTION_API_URL": "https://your-instance.example.com",
        "EVOLUTION_API_KEY": "your-key"
      }
    }
  }
}

工具（25 个）

工具	用途
send_text	通过 WhatsApp 发送文本消息
send_image	通过 WhatsApp 发送图片消息
send_document	通过 WhatsApp 发送文档
get_instances	列出所有 WhatsApp 实例
create_instance	创建新的 WhatsApp 实例
get_qrcode	获取实例配对用的二维码
get_contacts	获取实例中的联系人
send_poll	通过 WhatsApp 发送投票消息
get_messages	获取聊天消息
check_number	检查电话号码是否已注册 WhatsApp
create_group	创建 WhatsApp 群组
get_group_info	获取群组元数据、参与者和设置
update_profile	更新实例资料（名称、状态文本或头像）
set_presence	设置实例的在线／离线状态
get_chat_history	获取完整聊天记录，支持分页
logout_instance	注销实例（断开 WhatsApp 会话，但不删除实例）
restart_instance	重启实例
delete_instance	永久删除实例
connection_state	获取实例的连接状态（open、connecting、close）
leave_group	退出 WhatsApp 群组
update_group_participants	在 WhatsApp 群组中添加、移除、提升或降级参与者
fetch_group_invite_code	获取 WhatsApp 群组的邀请码／链接
mark_message_as_read	将聊天中的一条或多条消息标记为已读
archive_chat	归档或取消归档聊天
delete_message	删除聊天中仅对自己或对所有人可见的消息

身份验证

Evolution API 使用通过 apikey 标头传递的 API 密钥。

沙盒／测试

Evolution API 可自托管。使用 Docker 部署自己的实例进行测试。

获取凭据

1. 前往 Evolution API 文档
2. 部署自己的实例（推荐使用 Docker）
3. 从实例配置中获取 API 密钥
4. 设置环境变量

环境变量

变量	必填	描述
EVOLUTION_API_URL	是	Evolution API 实例的基础 URL
EVOLUTION_API_KEY	是	用于身份验证的 API 密钥

路线图

v0.2（计划中）

• create_group — 创建 WhatsApp 群组
• get_group_info — 获取群组详情和参与者
• update_profile — 更新实例资料（名称、照片、状态）
• set_presence — 设置在线／离线状态
• get_chat_history — 获取与联系人的完整聊天记录

v0.3（计划中）

• bulk_send — 向多个联系人发送消息
• template_messages — 发送 WhatsApp Business 模板消息
• label_management — 创建、更新聊天标签并为聊天分配标签

想要贡献？提交 PR 或请求添加工具。

链接

• Evolution API 文档
• Evolution API GitHub
• MCP Dev LATAM
• 项目主页

企业版

需要为 Agent 付款设置治理、预算限制和审计跟踪？CodeSpar Enterprise 可在这些 MCP 服务之上提供策略引擎、付款路由和合规模板。

许可证

MIT