在 Cloudflare Workers 上运行 WhatsApp MCP——只读 AI 驱动的消息访问

TL;DR——WhatsApp MCP 的功能及其重要性

WhatsApp MCP 是一个自托管的只读服务器，运行在 Cloudflare Workers 上，允许 AI 代理（例如 Claude Code）搜索和读取你自己的 WhatsApp 聊天记录，而无需发送消息。它将消息存储在 Durable Object 内的私有 SQLite 数据库中，在保持数据可控的同时，提供标准的 MCP 接口。

核心功能——AI 代理可以查询你的聊天历史

搜索和读取：代理可以在所有聊天或特定对话中运行 search_messages，并通过 get_messages 分页浏览聊天记录。
聊天发现：list_chats 返回最近的聊天列表，可选地按名称或号码过滤。
命名辅助：unnamed_chats 会列出仅有电话号码的聊天；代理可以调用 set_contact_names 来附加人类可读的名称。
按需同步：如果存储的副本超过十分钟未更新，sync_now 会强制立即从 WhatsApp 拉取。
只读保证：服务器从不发送消息；它只读取 WhatsApp 提供给关联设备的内容。

架构——系统如何保持隐私和轻量

Durable Object 作为唯一数据源：所有消息、联系人和 Baileys 认证数据都存储在一个 Durable Object（WhatsAppStore）内的 SQLite 数据库中。
无状态 Cloudflare Worker：Worker 处理 HTTP/MCP 路由、OAuth 和每日定时触发拉取。它本身不保存任何消息数据。
Baileys 库：使用开源的 WhatsApp Web 客户端库来模拟关联设备。代码包含三个 shim（ws-shim.ts、vendor-bridge.mjs、polyfills.ts），使 Baileys 能在 Cloudflare 的 workerd 运行时上运行。
OAuth 保护：密码（OWNER_PASSWORD）或可选的基于邮箱的登录保护 /mcp 端点。令牌存储在 KV 命名空间（OAUTH_KV）中。
无外部存储：除了用于 OAuth 令牌的 Cloudflare KV 之外，所有数据都保存在 Durable Object 内部；不会向第三方存储发送任何数据。

部署步骤——从零到可用的端点

前提条件：Cloudflare 账户需使用 Workers 付费计划，Node 20+，以及一部装有 WhatsApp 的手机。

克隆并安装：

git clone https://github.com/finereli/whatsapp-mcp
cd whatsapp-mcp
npm install

为 OAuth 令牌创建 KV 命名空间：

npx wrangler kv namespace create OAUTH_KV

设置强所有者密码（12 个字符以上）：
```
npx wrangler secret put OWNER_PASSWORD
```
部署：
```
npm run deploy
```
Wrangler 会输出一个类似 https://whatsapp-mcp.<your‑name>.workers.dev 的 URL。
关联 WhatsApp：打开该 URL，扫描 WhatsApp → 设置 → 已链接设备中的二维码。首次链接会导入 WhatsApp 提供的任何历史记录。
连接 MCP 客户端（例如 Claude Code）：
```
claude mcp add --transport http whatsapp https://<your-url>/mcp
```
然后运行 /mcp 并使用密码登录。

操作说明——使用或修改项目前需要了解的内容

服务条款风险：该项目使用了与 WhatsApp Web 相同的逆向工程协议，这违反了 WhatsApp 的服务条款。对于只读的关联设备，实际风险较低，但并非为零。
导入限制：初始历史记录导入可能超出 Workers 的默认 CPU 限制；仓库中的 wrangler.jsonc 提高了该限制，这需要付费计划。
数据完整性：WhatsApp 只发送其认为适合新设备的部分历史记录。要填补空白，你必须重新关联设备。
未命名聊天：许多一次性联系人仅显示为电话号码。代理可以通过调用 unnamed_chats，然后使用你自己的联系人存储中的数据调用 set_contact_names 来解析这些联系人。
媒体处理：媒体文件不会被下载；它们会以 [image] 或 [voice note 12s] 等占位符形式出现。
单用户设计：每次部署仅绑定一个 WhatsApp 账户；多用户支持需要重新设计 Durable Object 的键控。

扩展服务器——添加工具或更改认证

添加新的 MCP 工具：在 src/mcp.ts 中注册，并在 src/store.ts 中实现所需的 SQL。保持只读工具的幂等性。
切换认证模式：src/auth.ts 支持基于密码或电子邮件的登录。添加其他身份提供商只需新增一种模式和回调路由；其余代码将其视为不透明的 Bearer 令牌。
多用户扩展：将固定的 Durable Object 名称（owner）替换为从登录身份派生的每用户标识符，并相应调整 OAuth 负载。
自定义名称导入：任何能够生成 { jid, name } 行的外部进程都可以调用 store.setCustomNames。这支持 CSV 上传、CardDAV 同步或定时任务，而无需向服务器暴露凭据。
发送消息：该项目有意省略了写入功能。添加该功能需要仔细的安全审查，因为这将把关联设备变成一个功能完整的机器人，从而增加账户被封禁的风险。

调试与测试——内置诊断工具

设置可选 PIN 密钥后，以下端点返回 JSON 以进行故障排除（需包含标头 x-pin: <PIN>）：

/debug——显示会话阶段、关联状态和最近事件。
/debug/pull——强制立即拉取。
/debug/*——各种只读查询（chats、messages、search、unnamed、sql）。
/debug/logout——触发与 relink 相同的流程。

本地开发可通过 npm run dev 和包含 OWNER_PASSWORD 的 .dev.vars 文件运行。这会启动一个存储为空的本地 Durable Object，允许你在不影响生产部署的情况下测试二维码配对流程。

社区反应——Hacker News 讨论亮点

"AI 为我构建了一个 Android 网关，可以发送/读取短信……软件构建完成后，零 SaaS、零第三方、零购买。" – @pizzafeelsright

"让我困扰的是将对话的另一端暴露给第三方 AI 公司……你正在聊天的人从未同意。" – @SchemaLoad

"我尝试过 WhatsApp 网页版的 hack，有时会被封禁；如果 WA 是通用联系渠道，那就很不方便。" – @taldo

"听起来免费套餐可能不够用；仓库说明初始导入需要付费套餐。" – @calmingsolitude

"我在关联辅助设备后被封禁；WhatsApp 可以永久封禁添加非官方关联设备的账户。" – @lgleason

这些评论凸显了任何非官方 WhatsApp 集成所伴随的隐私、法律和可靠性问题。

总结

WhatsApp MCP 证明了可以在 Cloudflare Workers 之上构建一个个人、只读的 AI 助手，而无需将数据存储在外部。它提供了一个具体示例，展示了如何结合 MCP 协议、Baileys 和 Cloudflare Durable Objects，让 AI 代理能够访问你自己的消息上下文——同时也揭示了逆向工程 WhatsApp 集成所带来的法律和运营上的权衡。

SUMMARY: WhatsApp MCP 是一个运行在 Cloudflare Workers 上的只读服务器，允许 AI 代理通过 MCP 协议搜索和读取你的个人 WhatsApp 消息。

TITLE: 在 Cloudflare Workers 上运行 WhatsApp MCP——只读 AI 驱动的消息访问