whatsapp-connect-mcp

一个以单一静态 Go 二进制文件形式提供的 WhatsApp MCP 服务器。一次下载，一次 setup 命令，一次二维码扫描——然后任何 MCP 客户端（Claude Desktop、Claude Code、Cursor、Windsurf、Cline 等）都可以读取、搜索和发送 WhatsApp 消息，每次外发发送都受服务器强制执行的网关保护。

这使用的是非官方协议。在绑定你重视的号码之前，请先阅读此内容。

whatsapp-connect-mcp 通过 whatsmeow 与 WhatsApp 对话，方式与 WhatsApp Web 相同——而非官方 WhatsApp Business API。Meta 可以并且确实会封禁检测到在此协议上使用第三方客户端的号码，此类封禁被广泛报道为永久性的。下文描述的发送网关和速率限制器降低了该风险的行为部分（意外的批量发送、模型失控）；它们无法触及另一半，即该客户端本身可被识别为第三方客户端。封禁风险 列出了公开证据实际显示的内容，并附有日期。绑定一个你愿意失去的号码，而不是你与银行或家人联系的唯一线路。

状态：预发布版。

安装（两分钟）

选择一种方式：

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/idle-sync/whatsapp-connect-mcp/main/scripts/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/idle-sync/whatsapp-connect-mcp/main/scripts/install.ps1 | iex

# Anywhere with Node installed, no separate download step
npx whatsapp-connect-mcp setup

npx whatsapp-connect-mcp serve 本身可以正常工作，但对于 setup，建议使用上述安装脚本之一。setup 会将运行中二进制文件的绝对路径注入到每个 MCP 客户端的配置中，而在 npx 下，该路径位于 npm 的包缓存中——清除该缓存后，setup 写入的每个客户端配置都将指向一个已不存在的二进制文件。

以上每种方式都会下载适用于你操作系统/架构的发布二进制文件并运行 setup：它显示一个二维码供你从 WhatsApp 扫描（已链接设备 → 链接设备），然后检测已安装的 MCP 客户端，并提供将 whatsapp 服务器条目注入到你选择的任何客户端中。无需工具链，无需手动编辑 JSON。

setup 还会询问客户端如何连接。stdio（默认）让每个客户端启动自己的服务器进程——最简单，但一次只能连接一个客户端或会话，因为一个 serve 持有数据目录的独占锁。http 将所有选定的客户端指向一个共享的本地服务器（http://127.0.0.1:<port>，端口自选，默认 2178，Bearer 令牌认证），这样多个客户端和会话可以同时连接——代价是你需要自己使用 whatsapp-connect-mcp serve --http 127.0.0.1:<port> 启动该服务器，并且客户端只能在其运行时连接。

setup 可以随时重新运行——用于重新配对，或添加之后安装的客户端。

传递 --full-history 以向手机请求协议允许的尽可能多的历史记录，而不是默认的几个月。它仅在配对时生效，因此已配对的安装必须先执行 remove；setup 会提示这一点，而不是静默忽略该标志。手机仍然决定实际发送什么。

Related MCP server: WhatsApp MCP

它的用途

十四个读取工具是核心产品；十个带网关的写入工具是便利性功能。实际上这意味着：

• 搜索你自己的历史记录。 WhatsApp 自己的搜索没有日期过滤器，并且显示匹配项时没有上下文。search_messages 加上 get_message_context 可以同时做到这两点。

• 快速跟上进度。 让模型阅读你离开时群组积累的 400 条消息，并询问发生了什么。

• 读取你自己的附件。 download_media 下载人们发送给你的发票、收据和截图，以便模型能实际读取它们。

• 查找未处理事项。 get_last_interaction 回答“谁给我发了消息但我从未回复？”

• 起草回复。 模型撰写，发送网关让你确认，然后发送。

• 与其他内容一起搜索 WhatsApp。 当邮件、聊天或日历 MCP 服务器连接到同一客户端时，“这个客户有没有联系过我关于发票的事，以及在哪里？”就变成了一个查询，而不是三个独立的搜索。对于真正在 WhatsApp 中进行通信的人来说，这是运行它的理由。

不要用它做什么

不要在此之上构建支持机器人、外联工具或自动回复器。向从未主动联系你的人批量发送消息，是最常被报道导致号码被封禁的行为（参见封禁风险）——而这正是 Meta 销售 WhatsApp Business API 的用例。这是一个用于你自己消息的个人工具。将其用于客户，你将失去该号码。

它给你的 MCP 客户端提供什么

二十四个工具：十四个只读，十个带网关，如下所述。

读取 / 搜索（无网关）

这些工具能回溯多远的范围由配对手机决定，而非此服务器。 “搜索我的全部历史记录”可能实际意味着“搜索最近几个月”——参见限制。

发送（带网关——见下文）

每个来自 WhatsApp 数据的工具结果——消息、名称、联系人、说明文字——都包裹在显式的不可信数据横幅中。将其视为 MCP 客户端向您展示的数据，而不是模型应遵循的指令：通过 WhatsApp 到达的任何内容都不能指示您的助手该做什么。

发送门控

这是 verygoodplugins/whatsapp-mcp 所没有的部分。每个出站操作——文本、媒体、语音消息、反应、编辑、删除、投票、屏蔽、解除屏蔽或已读回执——都经过同一条路径，由服务器强制执行，而不是通过提示模型“要小心”：

1. 先草稿。 对您尚未信任的收件人调用发送工具，不会实际发送任何内容。您会收到一个预览（收件人解析为名称 + JID，以及确切的出站内容）和一个 draft_token。

2. 确认提交。 使用该 draft_token 重新发出相同的调用，即可发送。草稿在 5 分钟后过期；重新提交的内容有任何字节差异都会使令牌失效。

3. 有意识地信任。 whatsapp-connect-mcp trust --add <jid> 将联系人或群组标记为受信任，这样向其发送时将在第一次调用时直接提交，而无需草稿。这是一个仅限 CLI 的开关——没有 MCP 工具可以授予信任，因此模型无法绕过草稿步骤。正在运行的 serve 进程在启动时读取信任列表一次，因此更改将在下次 serve 启动时生效，而不是立即生效。对于当前会话，有一个更轻量级的授权：whatsapp-connect-mcp trust --session --add <jid> 仅在当前 serve 进程的生命周期内提升收件人——它立即生效，不会写入 config.json，并在下次 serve 启动时自动清除。当您正在积极与一个人或群组进行对话草稿，并且已经手动确认了前几次发送时，请使用此选项；它减少了该收件人的草稿-确认往返次数，而无需授予任何永久权限。与持久信任一样，它也是仅限 CLI（没有 MCP 工具可以授予），并且屏蔽/解除屏蔽仍然会在每次调用时草稿。

4. 始终限速。 每次发送——无论是草稿、信任还是其他——都会从所有五个发送工具共享的一个速率限制器中消耗一个令牌。间隔时间有 5 秒的硬性下限，任何配置都不能低于此值。被限速的提交会使草稿保持有效；一旦限制解除，使用相同的令牌重试相同的调用即可。

mark_read 是草稿机制的一个例外：已读回执不是创作内容，因此它总是在第一次调用时发送（仍然受速率限制，仍然受门控）。

发送可以附加哪些文件

上述门控授权的是收件人。它没有说明发送命名的文件，因此仅凭它本身，被操纵的模型可以将此程序可读取的任何内容（SSH 密钥、密码存储）附加到您已经信任的收件人。

因此，出站文件被限制在允许的目录列表中。默认是一个专用的目录，在首次运行时创建：

在发送文件之前将其移动到那里，或者通过在 config.json 中设置 media_roots 为绝对目录路径来扩大列表：

{ "media_roots": ["/home/you/Pictures", "/home/you/Documents"] }

路径在检查之前会被解析，因此允许目录内的符号链接会根据其实际指向的位置来判断，而不是其所在位置。命名列表外文件的发送将在第一次调用时被拒绝——在生成草稿和消耗速率限制令牌之前——并且拒绝信息不会包含路径，就像此服务器返回的所有其他错误一样。

与 verygoodplugins/whatsapp-mcp 的比较

当前最知名的替代方案虽然可用，但采用起来很麻烦，并且没有发送安全性：

封号风险

Meta 通过两种独立的方式检测第三方客户端，其中只有一种与行为有关。

1. 客户端可被识别。 链接设备在注册时会宣告自身。whatsmeow 的默认设置会宣告一个操作系统字符串为 whatsmeow，并带有未知的平台类型，仅通过读取配对负载即可将其与官方客户端区分开来。本项目覆盖了这一点，并宣告为 Chrome 浏览器身份（internal/bridge/bridge.go），这也是您的手机在“已链接设备”下为此设备显示的内容。

不要将该覆盖当作修复。它只击破了最简陋的版本检查，而未触及根本问题。serve 和 setup 确实会在连接前刷新报告的 WhatsApp Web 版本，因此版本及其派生的构建哈希会追踪真实的发布版，而非构建时打包的任意版本——但用户代理仍然携带 whatsmeow 的占位运营商和设备制造商字段，且会话在传输层的行为与 whatsmeow 一致，而非 Chrome。使用 whatsapp-web.js（它驱动真实的 Chrome 浏览器并携带真实的指纹）的用户也收到了下文描述的相同警告，这表明所声明的身份从来不是决定性信号。更改它对于已配对的会话也毫无作用：身份信息在配对时发送，因此现有会话会保留其注册时的身份，直到您重新配对。

2. 行为。 报告的触发因素，大致按出现频率排列：向从未主动联系过您的人发送消息、发送速度过高、配对后不久即高频发送、重复发送相同消息、自动状态更新以及频繁重连循环。

令人不安之处在于，公开证据指向 (1) 是主导因素。在 whatsmeow#810 —— 2025 年 5 月的“您的账户可能存在风险”浪潮（2026 年 7 月关闭并标记为 not planned）—— 用户报告警告出现在从未发送过消息、仅保持连接的空闲账户上，以及已断开连接数周的账户上。使用完全不同的实现 whatsapp-web.js 的用户也收到了该警告。同一条讨论中的 Baileys 维护者持相反观点，称其“主要是行为问题”。无人确定究竟是哪种原因，该讨论在未给出答案的情况下被关闭。

因此：此处的发送门控和速率限制是针对 (2) 的实际缓解措施，但对 (1) 毫无作用。根据现有证据，行为良好影响的是轮到您的时间，而非是否轮到您。

配对前值得阅读的报道，附日期供您判断其时效性：

将供应商博客中的封禁统计数据（如“68% 的企业在 12 个月内被封禁”、“滚动 30 天无回复阈值”）视为付费 Business API 转售商的无源营销信息。没有任何一手来源支持这些数据，因此这两个数字均不出现在本文档中。

限制（明确说明）

• 您的号码可能被封禁，且本项目无法阻止。 请参阅封禁风险。这是最重要的限制。

• 历史深度由手机决定。 与所有 WhatsApp Web 客户端一样，配对的手机控制同步到本服务器的聊天历史量。此处没有任何设置可以获取超出手机提供范围的历史。setup --full-history 请求协议允许的最大历史量，而非默认的几个月，但这只是一个请求，而非设置——且仅在配对时生效。对于已配对的安装，fetch_older_messages 工具会在不重新配对的情况下向手机请求更多单个聊天的历史。两者都是请求，手机可以回应较少的内容或不回应；也无法恢复手机已删除的消息。

• 语音消息需要 Ogg Opus 输入。 send_voice_note 不执行转码。如果您的源音频不是 .ogg/Opus 格式，请先转换（例如 ffmpeg -i in.mp3 -c:a libopus out.ogg）。

• 不支持呼出电话。 通话历史可读，但不支持发起呼叫。

• 每个安装只支持一个配对号码。 v1 版本不支持多账户。

• whatsmeow 跟踪 WhatsApp 协议变更，而非相反。WhatsApp 端的变更可能中断配对或发送，直到 whatsmeow（以及本项目的后续更新）赶上。

数据与隐私

所有内容——会话密钥、消息、媒体、联系人、通话记录——均存储在此程序数据目录下的本地 SQLite 数据库中。本服务器不会将您的任何消息、联系人或媒体数据发送到任何地方。

除了 WhatsApp 连接本身之外，仅存在两个出站网络调用。两者均为尽力而为，均在 2 秒后超时，且不携带消息内容、JID、电话号码或任何会话凭据：

• doctor/check 向 GitHub 的公开发布 API 查询此程序是否存在更新版本。当 GitHub 不可达时，它绝不会阻塞或导致检查失败。

• serve 和 setup 在连接前从 web.whatsapp.com 获取当前的 WhatsApp Web 客户端版本，以便此客户端报告的版本追踪真实的发布版，而非构建时打包的任意版本。失败会被报告并忽略；过时的版本仍能连接。

数据目录：

诊断

whatsapp-connect-mcp check

运行与 doctor MCP 工具相同的检查：会话配对/连接状态、事件流活性（已连接但超过 30 分钟未收到任何 WhatsApp 事件的会话会收到警告——即套接字看似健康但数据摄取已静默停滞的状态）、消息数据库完整性、已注入的 MCP 客户端配置、数据目录权限（POSIX）以及上述版本检查。每项发现均经过清理——状态行中绝不出现 JID、电话号码、消息内容或文件系统路径；损坏的客户端配置通过客户端名称标识，而非其在磁盘上的路径。

其他命令

whatsapp-connect-mcp setup [--full-history]  # pair (again) and configure MCP clients
whatsapp-connect-mcp status                  # pairing state, row counts, injected clients
whatsapp-connect-mcp clients [--remove]      # list or uninject MCP client entries
whatsapp-connect-mcp trust [--session] [--add jid|--remove jid|--list]
whatsapp-connect-mcp serve [--http addr]     # run the MCP server directly (stdio by default)

--http 需要 Bearer 令牌和回环 Host。 首次使用时，它会生成一个 256 位令牌，写入数据目录中的 .http-token 文件（仅限所有者），并打印一次——请将其放入客户端的 Authorization: Bearer <token> 标头中。每个请求还必须指向回环 Host（localhost、127.0.0.1、[::1]），这可通过将 DNS 重新绑定到回环地址来阻止网页通过浏览器访问服务器。仍需绑定 127.0.0.1：令牌可防止端口被访问，但绑定公共接口会将其暴露在整个网络中；如果必须如此，请在前端设置自己的访问控制（反向代理、VPN、防火墙规则）。

卸载 / 重置

• whatsapp-connect-mcp remove 删除本地 WhatsApp 会话（在本地解除本服务器与它的配对——再次运行 setup 需要重新配对）。此操作仅限本地：它不会通知 WhatsApp 服务器，因此您的手机将在“已链接的设备”下继续显示此设备已链接，直到您自行在手机上取消链接。执行任何操作前会要求输入 yes 确认。

• whatsapp-connect-mcp reset 执行 remove 的所有操作，外加删除已存储的消息、媒体和设置——完全擦除至全新安装状态。同样要求输入 yes 确认。

• whatsapp-connect-mcp clients --remove 从已添加的任意 MCP 客户端配置中移除本程序的条目，不影响已配对的会话。

• 要移除二进制文件本身，请从安装程序放置的位置（~/.local/bin、%LOCALAPPDATA%\Programs\whatsapp-connect-mcp 或 npx 缓存的位置）删除它，并删除上述数据目录。

许可证

MIT — 请参阅 LICENSE。