whatsapp-mcp

whatsapp-mcp 是一款开源MCP服务，部署在用户自己的Cloudflare Workers环境中，作用是让支持MCP的AI代理读取、检索WhatsApp聊天消息，仅支持读取，无法发送消息。

使用逻辑类似WhatsApp Web配对：手机扫码绑定一次之后，Claude Desktop、Claude Code等MCP客户端就可以检索聊天记录、按关键词查找消息、汇总群聊内容；还支持手动给陌生号码备注名称。
典型提问示例：

• “Dana关于航班说了什么？”
• “找出所有提到租约的消息”
• “总结本周家庭群错过的消息”

工作原理

手机端仍然是消息源，服务不会保持长连WhatsApp。AI发起查询、以及每日自动拉取一次增量消息，拉取完成后就断开连接；消息数据保存在你Cloudflare账号内Durable Object的SQLite数据库，不会外流。

部署要求

需要 Cloudflare Workers Paid 付费套餐（首次导入大量历史消息CPU开销高，免费版容易失败，可手动移除限制块尝试但不稳定）、Node 20+环境。

git clone [https://github.com/finereli/whatsapp-mcp](https://github.com/finereli/whatsapp-mcp)
cd whatsapp-mcp
npm install

# 创建KV存储
npx wrangler kv namespace create OAUTH_KV
# 设置访问密码（≥12位）
npx wrangler secret put OWNER_PASSWORD

npm run deploy

部署完成后访问输出的workers.dev地址：扫码绑定WhatsApp；再在MCP客户端接入服务地址 /mcp，Claude Code接入命令：

claude mcp add --transport http whatsapp https://your-url/mcp

重要限制与风险提示

• ❗非官方方案：依托Baileys库复用WhatsApp Web协议，违反WhatsApp用户协议，虽然只读场景封禁风险相对低，但风险始终存在，仅用于自己账号
• 历史消息不全：首次绑定仅导入WhatsApp开放给链接设备的历史记录，不会拿到全部消息；重新扫码可补拉，已有本地数据不会丢失
• 媒体不下载：图片、语音、文档只会标记[image]这类占位符，不会自动拉取、转写
• 单用户设计：一个部署实例对应单个WhatsApp账号
• 联系人名称缺失：陌生号码聊天默认只显示号码，支持手动给号码命名