Evolution WhatsApp

evolution-whatsapp-mcp

一个 MCP 服务，让 Claude（以及任何 MCP 客户端）能够使用 WhatsApp。 它可以通过 Evolution API 发送和读取消息、发送媒体并管理连接。将它添加到 Claude Desktop/Code 后，你的 Agent 就能连接一个 WhatsApp 号码并与他人交流。

客户端代码来自一款多租户诊所 SaaS 的 WhatsApp 集成。所有九个工具最后一次是在 2026 年 10 月针对真实的 Evolution API 2.3.7 服务进行检查的。

架构与运行位置

Claude (Desktop/Code)        evolution-whatsapp-mcp          Evolution API        WhatsApp
     [MCP client]   ──stdio──►   (this package)    ──HTTP──►   (gateway)  ──────►  (phone)

• 此 MCP 服务按需在本地运行，无需托管。 你的 MCP 客户端（Claude Desktop/Code）会通过标准输入/输出将其作为子进程启动（npx evolution-whatsapp-mcp）；客户端需要时它就会启动，客户端关闭时它就会退出。无需开放端口，也无需部署。
• Evolution API 必须持续运行，因为它会保留 WhatsApp 会话（类似 WhatsApp Web：如果它停止运行，号码就会断开连接）。你可以通过 Docker 在本地运行来试用；如果需要全天候在线（例如通过 webhook 接收消息），则可以将它运行在小型 VPS 上。此服务只需要它的 URL 和 API 密钥。
• 此服务是无状态的。它没有数据库，也不会存储消息，只会将 MCP 客户端的调用转发给 Evolution API。

工具

工具	描述
send_text	向电话号码发送文本消息
send_media	发送图片／视频／文档／音频（URL 或 base64）
find_chats	列出实例中的对话（limit，默认值为 50，最大值为 200）
find_messages	读取聊天记录（按电话号码或 JID），支持 limit（默认值为 50，最大值为 200）和 page
create_instance	创建新实例（一个 WhatsApp 连接槽位）
get_qrcode	获取用于关联 WhatsApp 号码的 QR 码（base64）
connection_status	检查实例是否已连接
disconnect_instance	退出实例中的 WhatsApp 号码
configure_webhook	将实例的 webhook 指向公共 URL

每个工具都接受可选的 instance 参数；如果省略，则使用 EVOLUTION_DEFAULT_INSTANCE。

工具带有 MCP 注解：读取类工具标记为只读，而 disconnect_instance 和 configure_webhook 标记为破坏性操作，客户端可在执行前请求确认。

find_messages 支持带或不带第九位数字的巴西电话号码。WhatsApp 会将部分聊天记录存储在短格式号码下，因此如果使用第一种格式时没有消息，该工具会尝试另一种格式。

前置条件

需要运行中的 Evolution API 服务（v2.x）及其 API 密钥。在本地运行的最快方法是使用示例 docker-compose.yml（Evolution API v2，以及它所需的 Postgres 和 Redis）。使用本地 Docker 进行试用，或使用 VPS 实现 24/7 运行：

EVOLUTION_API_KEY=my-secret-key docker compose up -d

它会监听 http://localhost:8080。接入 MCP 服务时，请将 EVOLUTION_API_KEY 设置为相同的值（见上文）。该 compose 文件仅用于起步，并非生产环境配置。

安装和配置

Claude Code 一行命令：

claude mcp add evolution-whatsapp \
  -e EVOLUTION_API_URL=http://localhost:8080 \
  -e EVOLUTION_API_KEY=your-evolution-api-key \
  -- npx -y evolution-whatsapp-mcp

对于其他客户端，请将其添加到 MCP 客户端配置中。对于 Claude Desktop / Claude Code（mcpServers 配置）：

{
  "mcpServers": {
    "whatsapp": {
      "command": "npx",
      "args": ["-y", "evolution-whatsapp-mcp"],
      "env": {
        "EVOLUTION_API_URL": "http://localhost:8080",
        "EVOLUTION_API_KEY": "your-evolution-api-key",
        "EVOLUTION_DEFAULT_INSTANCE": "my-whatsapp"
      }
    }
  }
}

环境变量	必需	说明
EVOLUTION_API_URL	是	Evolution API 服务的基础 URL
EVOLUTION_API_KEY	是	Evolution API 密钥（通过 apikey 标头发送）
EVOLUTION_DEFAULT_INSTANCE	否	工具未提供 instance 时使用的默认实例
EVOLUTION_TIMEOUT_MS	否	每个请求的超时时间，单位为毫秒（默认值为 30000）
EVOLUTION_READ_ONLY	否	设置为 true、1 或 yes（不区分大小写）时，会隐藏 send_text、send_media、create_instance、disconnect_instance 和 configure_webhook。其他任何值都会保留这些工具
EVOLUTION_CONFIRM_WRITES	否	设置为 true、1 或 yes（不区分大小写）时，send_text、send_media、create_instance、disconnect_instance 和 configure_webhook 都会等待人工确认。不支持显示确认提示的客户端会被拒绝，且不会发送任何内容。false、0、no 或空值表示关闭（默认值）。其他任何值（例如拼写错误的 ture 或 on）都视为开启，并会在 stderr 输出警告
EVOLUTION_ALLOWED_NUMBERS	否	以逗号分隔的号码列表，send_text 和 send_media 只能发送到这些号码（例如 5511999999999,5521988887777）。留空表示不限制。巴西号码无论是否包含第 9 位数字都能匹配；设置此列表后会拒绝群组 JID

由于这些工具由大模型驱动，通过收到的消息注入的提示词可能会要求它发送内容。EVOLUTION_READ_ONLY 和 EVOLUTION_ALLOWED_NUMBERS 可以限制它的操作。

内置限制：find_chats 和 find_messages 接受 limit（1-200，默认值为 50）；任何超过 100,000 个字符的响应都会被截断并附带提示；get_qrcode 会丢弃过大的 base64 图像并保留配对码。configure_webhook 仅接受 https URL（localhost、127.0.0.1 和 [::1] 可使用普通 http）。如果 EVOLUTION_API_URL 既不是 https，也不是 localhost，服务会在 stderr 输出警告，因为 API 密钥将以未加密的形式传输。

写入前确认

工具描述只是建议，并非限制：模型仍然可以调用 disconnect_instance 来“重启连接”。设置 EVOLUTION_CONFIRM_WRITES=true 后，服务会暂停每项写入操作（send_text、send_media、create_instance、disconnect_instance、configure_webhook），直到用户通过客户端确认；这是模型无法控制的渠道。默认情况下此功能关闭，因此无头自动化仍可正常工作；有人参与操作时，请将其开启。

用户看到的是简短预览：操作、部分遮盖的收件人号码（+55 11 9****-9999），以及最多 200 个字符的文本。不会显示媒体内容、Webhook 路径或查询字符串。对话框默认选择“否”，并等待 120 秒；除明确选择“是”以外的任何情况（拒绝、取消、超时、错误）都不会发送任何内容。

客户端声明的能力	结果
表单式引导（elicitation，如 Claude Code）	每次写入前都会显示是/否对话框
其他任何情况（无相应能力、仅 URL 式引导、仅支持 MCP Apps）	写入会被拒绝，并返回 isError，不会发送任何内容

面向 MCP Apps 客户端的确认卡片不包含在此版本中。Claude Code 不会呈现 MCP Apps（客户端矩阵见 modelcontextprotocol/modelcontextprotocol，2026-11-03），因此会使用对话框。据报告，某些 Claude Code 版本会自动拒绝引导表单；在这种情况下，写入会被拒绝，不会发送。

此功能与其他限制共同生效：首先检查 EVOLUTION_ALLOWED_NUMBERS（不在列表中的号码会直接被拒绝，不会询问），而启用 EVOLUTION_READ_ONLY 后则没有可供确认的写入工具。

端到端示例流程

询问 Claude：

1. “创建一个名为 my-whatsapp 的 WhatsApp 实例，并显示二维码。” → create_instance + get_qrcode（用手机扫描二维码）。
2. “连接了吗？” → connection_status。
3. “向 +55 11 99999-9999 发送‘您的预约已确认’。” → send_text。
4. “对方回复了什么？” → find_messages。

故障排查

症状	原因及解决方法
HTTP 401 / Unauthorized	EVOLUTION_API_KEY 与服务端的 AUTHENTICATION_API_KEY 不匹配。
超时 / fetch failed	URL 错误，或 Evolution API 已停止运行。在浏览器中打开 EVOLUTION_API_URL；如果服务端响应缓慢，请提高 EVOLUTION_TIMEOUT_MS。
发送失败，实例不是 open 状态	实例尚未连接。运行 connection_status，然后运行 get_qrcode 并用手机扫描二维码（WhatsApp > 已关联的设备）。
find_messages 未返回巴西号码的任何结果	WhatsApp 可能会以包含或不包含第九位数字的形式存储聊天记录。该工具会尝试两种形式；请检查号码是否包含国家代码（55）。
number must be a phone with 8 to 15 digits	请传入包含国家代码的完整号码，或包含 @ 的 JID。
Webhook URL 被拒绝	configure_webhook 要求使用 https（仅 localhost、127.0.0.1、[::1] 可使用 http）。类似 localhost.evil.com 的伪装主机名会被拒绝。
工具列表中缺少 send_text	已启用 EVOLUTION_READ_ONLY。取消设置该变量，或将其设为 false。
Recipient is not in EVOLUTION_ALLOWED_NUMBERS	该号码不在允许列表中。请将其添加进去，或将该变量留空。
响应以 truncated: use limit/page 结尾	载荷超过了 100,000 个字符。请调低 limit，或逐页读取。

目录索引

官方 MCP 注册表的元数据位于 server.json 中，Smithery 的元数据位于 smithery.yaml 中。 Glama 会根据此 README 和 package.json 索引公开的 GitHub MCP 服务，因此请确保两者信息准确。

开发

npm install
npm run build      # tsc → dist/
npm test           # vitest (mocks the Evolution API; no server needed)
npm run lint       # tsc --noEmit

使用 MCP Inspector 在本地检查服务：

EVOLUTION_API_URL=http://localhost:8080 EVOLUTION_API_KEY=key \
  npx @modelcontextprotocol/inspector node dist/index.js

工作原理

轻量级 REST 客户端（src/evolution.ts）封装 Evolution 端点，并使用 apikey 请求头进行身份验证。src/tools.ts 使用 zod 输入架构将各项操作注册为 MCP 工具； src/index.ts 通过 stdio 提供这些工具。

许可证

MIT © Ewerton Silva