跳到主要内容
AI教程

使用 whatsapp-mcp 构建私有 WhatsApp 消息搜索服务器

了解如何将 whatsapp-mcp 部署到 Cloudflare、关联 WhatsApp 账号、连接 Claude 或其他 MCP 客户端、搜索和读取消息、解析未命名联系人，并在将消息数据保存在自己账号中的同时排查同步问题。

AI我搜编辑部阅读约 10 分钟
使用 whatsapp-mcp 构建私有 WhatsApp 消息搜索服务器

whatsapp-mcp 的功能

whatsapp-mcp 是一个小型服务器，可让兼容 MCP 的 AI 代理读取和搜索你的 WhatsApp 消息。它运行在你自己的 Cloudflare 账户中，并以类似 WhatsApp Web 的已关联设备连接到你的手机。

完成初始设置后，Claude Code、Claude Desktop 或其他 MCP 应用等客户端可以回答以下问题：

  • Dana 对航班说了什么？
  • 查找所有聊天中提到租约的消息。
  • 总结本周我错过的家庭群聊内容。

该服务器特意设计为只读：它可以收集、搜索和显示消息，但不能发送 WhatsApp 消息。

系统工作原理

你的手机仍然是事实来源。Cloudflare 部署会作为一台已关联设备，仅在需要同步数据或配对账户时连接到 WhatsApp。

当代理请求信息时，如果服务器中存储的副本已超过十分钟未更新，服务器会从 WhatsApp 获取排队的更新。系统还会每天自动执行一次定时拉取。收集消息后，服务器会再次断开连接。你的手机会继续正常工作并接收通知。

消息存储在你账户中 Cloudflare Durable Object 内的 SQLite 数据库中。服务器不会将你的消息历史记录发送到外部存储服务。

前提条件

安装前，请准备以下内容：

  • 一个使用 Workers Paid 计划的 Cloudflare 账户。
  • Node.js 20 或更高版本。
  • 一部拥有要关联的 WhatsApp 账户的手机。
  • 一个 MCP 客户端，例如 Claude Code 或 Claude Desktop。

Workers 付费计划很重要，因为导入大量 WhatsApp 历史记录可能超过默认 CPU 限制。仓库在 wrangler.jsonc 中提高了该限制，而 Cloudflare 要求使用付费计划才能获得更高的限制。

安装并部署

克隆仓库、安装依赖项、创建所需的 KV 命名空间、存储所有者密码，然后部署 Worker：

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

npx wrangler kv namespace create OAUTH_KV
npx wrangler secret put OWNER_PASSWORD
npm run deploy

密码必须至少包含 12 个字符。部署完成后，Wrangler 会打印类似 https://whatsapp-mcp.your-name.workers.dev 的 URL。打开该 URL 继续设置。

如果你想使用自定义域名，请按照 wrangler.jsonc 底部的注释操作。

关联你的 WhatsApp 账户

部署页面会提供剩余的设置步骤。

  1. 选择关联 WhatsApp 的选项。
  2. 在手机上打开 WhatsApp，依次进入设置、已关联的设备和关联设备。
  3. 扫描服务器显示的二维码。如果你使用的就是同一部手机，无法扫描该手机屏幕，请改用手机号配对选项。
  4. 等待首次关联完成导入 WhatsApp 向新设备提供的历史记录。

页面会显示导入进度，导入过程中你可以关闭页面。首次导入可能不会包含所有历史消息，因为 WhatsApp 会决定向新关联的设备提供哪些历史记录。

连接 MCP 客户端

在 Claude Code 中，使用其 /mcp 端点注册已部署的服务器：

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

然后在 Claude Code 中运行 /mcp，并使用所有者密码登录。其他 MCP 客户端也应配置为使用同一个 URL：

https://your-url/mcp

完成身份验证后，让代理列出聊天、获取消息或搜索你的历史记录。

使用可用工具

MCP 服务器提供了用于读取和维护本地消息副本的专用工具：

  • list_chats 列出聊天，按最近消息优先排序，并支持按名称或号码筛选。
  • get_messages 读取某个聊天中的消息，并支持按日期向前或向后分页。
  • search_messages 在所有聊天中或指定聊天内执行全文搜索。
  • unnamed_chats 查找仅显示手机号的聊天，优先显示最活跃的聊天，并展示对方发来的最新消息。
  • set_contact_names 为电话号码保存姓名，使其也能在群聊中正确显示。
  • sync_now 立即拉取新消息。
  • link_status 报告账户是否已关联、上次同步时间以及已存储的数据量。
  • relink 移除当前关联并重新开始配对流程。已存储的消息仍然可用。

当存储的副本超过十分钟未更新时，读取工具会先自动同步。因此，你可以使用自然语言请求，而不必为每次查询手动调用 sync_now。

处理仅显示电话号码的聊天

有些聊天会显示为电话号码，因为 WhatsApp 不会向每台已关联设备提供所有联系人的姓名。这种情况常见于一次性对话，或对方未保存在你的 WhatsApp 联系人中。

向你的代理发送请求：

Find names for my unnamed chats.

代理可以调用 unnamed_chats，将号码与它已有的联系人集成进行比对，然后通过 set_contact_names 提交匹配结果。例如，Google Contacts 或 Gmail 连接器可能会提供匹配的姓名。服务器本身不会登录联系人服务。

保存的姓名会与电话号码关联，因此也可以用于群聊。有些号码在找不到匹配联系人时仍会没有姓名。

了解媒体和消息历史

媒体文件不会被下载。图像、语音消息和文档会以 [image] 或 [voice note 12s] 等标签表示。WhatsApp 提供标题时会保留标题，但不会转录语音消息。

首次链接会导入 WhatsApp 选择发送的全部历史记录。通常每个链接只会传送一次历史记录。如果导入不完整，重新链接可以请求再次导入，同时保留已经存储的消息。数据摄取设计为幂等操作，因此重新导入不会有意创建重复行。

重新链接账户

如果 WhatsApp 报告设备已被移除，或你想重新开始配对流程，请重新链接。让你的代理运行 relink，或打开 /setup 并选择 取消链接并重新扫描。

出现提示时扫描新的二维码。已存储的消息会被保留，新链接则可以补充缺失的历史记录。

高级配置

默认部署使用密码身份验证。主要配置值包括：

  • OWNER_PASSWORD：所有者密码，长度至少为 12 个字符。
  • OWNER_EMAIL：使用登录服务模式时唯一允许的电子邮件地址。
  • OPERATOR_NAME：隐私页面上显示的可选名称。
  • DEFAULT_COUNTRY_CODE：仅包含数字的国家代码，当代理保存未包含国家代码的号码时使用。
  • LOGIN_ORIGIN：将部署切换到登录服务模式。
  • ALLOWED_ORIGINS：登录服务令牌接受的来源。
  • PIN：可选的、长度至少为 32 个字符的值，通过 x-pin 标头启用受保护的调试路由。
  • OAUTH_KV 和 WA：应用使用的 KV 和 Durable Object 绑定。

将域名、KV ID 和电子邮件等部署专用值保存在被 git 忽略的 wrangler.local.jsonc 文件中。使用以下命令部署本地配置：

npm run deploy:local

调试同步问题

如果配置了 PIN，服务器会提供受保护的诊断端点。在 x-pin 标头中发送 PIN：

  • /debug 显示会话阶段、链接状态、计数和最近的会话事件。
  • /debug/pull 立即开始同步。
  • /debug/chats?q=、/debug/messages?chat=、/debug/search?q= 和 /debug/types 用于检查已存储的数据。
  • /debug/unnamed 显示由 unnamed_chats 返回的聊天。
  • /debug/sql?q= 针对存储运行一条只读 SELECT 查询。
  • /debug/logout 执行与重新链接等效的操作。

成功部署后，一个有用的验证流程是检查 /debug 是否报告会话处于空闲状态且账户已链接，运行 /debug/pull，然后测试聊天列表、消息检索、全文搜索、未命名聊天处理和联系人命名。

本地开发

进行本地开发时，创建一个 .dev.vars 文件，其中包含足够长的密码，然后启动 Worker：

OWNER_PASSWORD=your-12-character-or-longer-password

npm run dev

本地开发使用独立且存储为空的 Durable Object。它可以测试登录流程并显示真实的二维码，但在本地链接手机会创建另一个已链接设备。

提交代码更改前，运行：

npm run typecheck
npm test

测试套件会在 Node 22.13 或更高版本上使用 Node 内置的 SQLite 运行存储代码。该 SQLite 环境不覆盖全文搜索，因此部署后也应测试搜索功能。

重要的安全和平台注意事项

此项目不是官方的 WhatsApp 集成。WhatsApp 不提供读取个人消息的 API，而此项目通过开源 Baileys 库使用与 WhatsApp Web 相同的协议。此类使用可能违反 WhatsApp 的条款。仅使用你自己的账户，并记住：对于只读的已链接设备，实际风险较低，但并非为零。

一次部署面向一个人和一个 WhatsApp 账户。每次部署都会存储完整的消息历史和实时账户登录信息，因此用户应运行独立部署，而不是共享一个部署。

消息会保留在 Durable Object 的 SQLite 存储中，但任何获得部署凭据或所有者身份验证访问权限的人都可能访问已存储的历史记录。请妥善保护密码、Cloudflare 账户、密钥和任何调试 PIN。

结论

whatsapp-mcp 在 WhatsApp 的已链接设备协议与 MCP 客户端之间提供了实用的桥梁。将其部署到 Cloudflare，链接一次手机，将代理连接到 /mcp，然后使用 search_messages、get_messages 和 set_contact_names 等工具探索自己的消息存档。其只读设计、私有 Durable Object 存储、定时同步和明确的重新链接流程，使其适合个人消息搜索，同时让部署始终处于你的控制之下。