finereli/whatsapp-mcp
A read-only MCP server that lets your AI agent search and read your own WhatsApp messages. Use it free at whatsapp.finereli.com, or run your own copy on Cloudflare.
它是什么
whatsapp-mcp 是一个小型自托管服务器，允许 AI 代理（例如 Claude Code）读取和搜索您的 WhatsApp 聊天内容。它作为 Cloudflare Workers 服务运行，将消息存储在 Durable Object 内的 SQLite 数据库中，并公开一个简单的 MCP (Message-Control-Protocol) 端点供代理调用。
工作原理
- 连接 – 您从 Web UI 扫描二维码（或使用手机号码方式），就像将设备添加到 WhatsApp Web 一样。服务器成为一个已连接设备，并拉取 WhatsApp 为新设备提供的聊天记录。
- 存储 – 所有消息、聊天元数据和全文搜索索引都保存在 Durable Object 内的 SQLite 数据库中。数据不会发送到其他任何地方。
- 拉取 – 服务器每天（或按需）重新连接到 WhatsApp，获取自上次拉取以来收到的任何新消息，更新数据库，然后断开连接。手机功能保持正常。
- 代理访问 – AI 代理使用 MCP 工具集（列出聊天、获取消息、搜索等）与
/mcp端点通信。服务器首先确保数据库是最新的（如果超过 10 分钟则进行拉取），然后返回请求的数据。
主要功能 (MCP 工具)
| 工具 | 功能 |
|---|---|
list_chats |
返回按最近活动排序的聊天记录，支持可选的名称/号码过滤。 |
get_messages |
从单个聊天中检索消息，支持按日期分页。 |
search_messages |
在所有聊天或特定聊天内进行全文搜索。 |
unnamed_chats |
列出仅有电话号码（无已保存联系人姓名）的聊天。 |
set_contact_names |
为电话号码保存自定义名称；该名称将在以后的查询中使用。 |
sync_now |
强制立即拉取新的 WhatsApp 消息。 |
link_status |
显示设备是否已连接、上次拉取时间和存储大小。 |
relink |
取消设备连接以便扫描新的二维码；现有的存储消息会被保留。 |
设置步骤 (概览)
- 先决条件 – 拥有 Workers 付费计划的 Cloudflare 账户、Node 20+ 以及一部装有 WhatsApp 的手机。
- 克隆并安装 –
git clone … && npm install。 - 创建 KV 命名空间 –
npx wrangler kv namespace create OAUTH_KV并将打印出的 ID 粘贴到wrangler.jsonc中。 - 设置密码 –
npx wrangler secret put OWNER_PASSWORD(12 位以上字符)。 - 部署 –
npm run deploy。Wrangler 会打印一个 URL，例如https://whatsapp-mcp.your-name.workers.dev。 - 连接 WhatsApp – 打开该 URL，扫描二维码（或使用手机号码选项）。首次导入可能需要一些时间。
- 连接代理 – 在 Claude Code 中运行
claude mcp add --transport http whatsapp https://your-url/mcp，然后使用您设置的密码运行/mcp命令。
重要限制与风险
- 非官方 – 它使用与 WhatsApp Web 相同的逆向工程协议（通过 Baileys 库）。这违反了 WhatsApp 的服务条款；对于只读设备，实际风险较低，但并非为零。
- 只读 – 无法发送消息；服务器特意不公开发送 API。
- 仅限单用户 – 每个部署绑定到一个 WhatsApp 账户和所有者密码。多用户支持需要修改代码。
- 无媒体下载 – 图片、语音笔记等显示为占位符，如
[image]；它们不会被获取或转录。 - 联系人姓名 – 未保存联系人的聊天显示为电话号码。代理必须调用
unnamed_chats然后调用set_contact_names来为它们赋予可读名称。 - 付费 Cloudflare 计划 – 导入大量历史记录需要更高的 CPU 限制，这仅在付费 Workers 计划中提供。
- 潜在中断 – 由于服务器依赖于逆向工程协议，未来的 WhatsApp 更新可能会导致其停止工作。
适用人群
- 开发需要个人上下文的 AI 助手的开发者（例如：“我朋友关于航班说了什么？”）。
- 注重隐私、希望数据保留在自己的 Cloudflare 账户而非第三方服务的用户。
- 尝试使用 LLM 驱动的个人代理的研究人员。
许可证
MIT – 您可以自由使用、修改和部署此代码。
相关
- 项目
- 项目
- 项目
- 项目