WhatsApp Connect

whatsapp-connect-mcp

一个以单个静态 Go 二进制文件形式交付的 WhatsApp MCP 服务。下载一次、运行一条 setup 命令、扫描一次二维码——之后，任何 MCP 客户端（Claude Desktop、Claude Code、Cursor、Windsurf、Cline 等）都可以读取、搜索和发送 WhatsApp 消息，每条外发消息都受到服务端强制执行的门控保护。 这条一步完成的路径是默认的 stdio 传输方式；共享的 http 传输方式还多一个步骤——启动并保持服务运行（参见 安装（两分钟））。

此工具使用非官方协议。配对你在意的号码前，请先阅读本文。

whatsapp-connect-mcp 通过 whatsmeow，以与 WhatsApp Web 相同的方式连接 WhatsApp——而非官方的 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
# or, sturdier for setup: a global install
npm install -g whatsapp-connect-mcp

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 令牌进行身份验证），从而支持多个客户端和会话同时连接。

选择了 http？还需要执行第 2 步：启动服务。 它不会自动为你启动——在服务运行之前，每个客户端都会报告类似 ConnectionRefused at http://127.0.0.1:2178 的错误。运行以下命令（并保持运行）：

whatsapp-connect-mcp serve --http 127.0.0.1:2178

它会显示 serve: listening on http://127.0.0.1:2178 …，并在前台持续运行，因此终端关闭时它也会退出。若要在注销和重启后继续运行，请将其安装为后台服务 （macOS 上使用 launchd、Linux 上使用 systemd 用户单元，或 Windows 上使用任务计划程序登录任务）：

whatsapp-connect-mcp service install

service uninstall 会移除服务；service restart 会在更新后重启服务。在无头 Linux 机器上，添加 loginctl enable-linger，让服务在你注销后继续运行。在 Windows 上，服务会作为最小化的控制台窗口运行，并在用户登录时启动（而非开机时）；关闭窗口会停止服务。崩溃后不会自动重启（serve 在未配对状态下会空闲等待，而不是退出，因此常见故障模式不会导致进程退出）。创建任务可能需要在提升权限的（管理员）终端中进行。

setup 接着会询问这些客户端可以读取哪些内容：所有聊天（默认）、仅你自己的自我聊天，或暂不读取任何内容——之后你可以在仪表板中或使用 scope --allow 指定聊天。请参阅Agent 可以读取哪些聊天。

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

传入 --full-history，可让手机尽可能多地提供协议允许的历史记录，而不是默认的几个月记录。此选项仅在实际配对时生效，因此已配对的安装必须先运行 remove；setup 会明确提示这一点，而不会悄悄忽略该标志。手机仍会决定实际发送哪些内容。

适用场景

14 个读取工具是核心产品；10 个受限写入工具则是为了方便使用。 实际上，这意味着：

• 搜索自己的历史消息。 WhatsApp 自带的搜索没有日期筛选功能， 显示命中结果时也不会提供上下文。search_messages 和 get_message_context 可以同时做到这两点。
• 快速了解近况。 将某个群组在你离开期间积累的 400 条消息交给模型， 并询问发生了什么。
• 阅读自己的附件。 download_media 会下载别人发给你的发票、 收据和截图，以便模型实际读取。
• 查找未了事项。 get_last_interaction 可以回答“谁给我发过消息， 而我还没回复？”
• 起草回复。 模型负责撰写，发送限制会要求你确认，然后再发送。
• 与其他内容一并搜索 WhatsApp。 如果邮件、聊天或日历 MCP 服务已连接到 同一个客户端，那么“这位客户有没有联系我谈发票？在哪里联系的？”就会变成 一个问题，而不是三次单独搜索。对于真正的日常往来都在 WhatsApp 上的人来说， 这就是运行它的理由。

不适用场景

不要用它来构建客服机器人、外联工具或自动回复程序。大量向从未主动联系过你的人 发送消息，是最常被报告会导致号码被封禁的行为（参见 封禁风险）——而这恰恰是 Meta 销售 WhatsApp Business API 所面向的用例。这是一个供你处理自己消息的个人工具。把它用于客户，你就会失去这个号码。

它能为你的 MCP 客户端提供什么

共 24 个工具：14 个只读工具，10 个受限工具，详见下文。

读取 / 搜索（无门控）

工具	返回内容
list_chats	聊天（1:1 和群组），按最近活动时间从新到旧排列；可按名称和归档状态筛选。
get_chat	按 JID 获取单个聊天。
list_messages	聊天中的消息，按时间从新到旧排列，可选限定时间范围——传入具名时间窗口（today、yesterday、last_24h、last_7d）、带 IANA tz 的 date，或明确的起止时间（Unix 秒、RFC 3339 或纯日期）；时区计算由服务端完成。
search_messages	对消息正文进行全文搜索，可限定聊天范围，也可全局搜索。
get_message_context	获取目标消息前后的紧邻消息。
search_contacts	按姓名或电话号码片段搜索联系人。
get_last_interaction	获取涉及某个 JID 的最近一条消息。
list_group_participants	实时获取群组成员的 JID。
get_group_info	实时获取群组的主题、描述、群主和管理员。
get_blocklist	实时获取账号已屏蔽的 JID。
get_call_history	通话记录，按时间从新到旧排列，可选筛选单个联系人，并使用与 list_messages 相同的时间窗口 / 日期 / 时区格式限定时间范围。
download_media	将附件媒体下载到本地数据目录——可指定一条消息、一批消息 ID，或某个时间窗口内的所有媒体（使用与 list_messages 相同的时间窗口 / 日期 / 时区格式，可选按类型筛选）。
poll_new_messages	获取游标之后的新消息，按时间从旧到新排列——tail: N 会立即返回最新的 N 条；设置超时后最多阻塞 240 秒，直到有新消息到达，因此 Agent 无需重新读取聊天，也能响应动态。除非明确要求，否则不包含自己发送的消息。此工具只读；响应操作仍须通过发送门控。
fetch_older_messages	请求手机获取聊天中最早已存消息之前的消息，扩大可读取的历史范围。可重复调用以继续向前翻页。
doctor	以 MCP 工具的形式运行诊断中所述的检查。

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

这些工具能访问哪些聊天，由你决定：默认访问所有聊天，也可以设定 允许列表——请参阅 Agent 可以读取哪些聊天。

发送（受控 — 见下文）

工具	功能
send_message	发送文本，可选择引用现有消息。
send_media	从允许的目录发送图片、视频或文档，可选择添加说明文字。
send_voice_note	从允许的目录发送 Ogg Opus（.ogg）文件中的语音消息。不进行转码 — 不接受其他格式。
send_reaction	用表情符号回应某条消息（表情符号为空时会移除之前的回应）。
edit_message	在 WhatsApp 的编辑时限内编辑你发送的消息文本。
delete_message	为所有人删除消息（你自己的消息始终可以删除；他人的消息仅群组管理员可以删除）。
create_poll	创建投票（一个问题和两个或更多选项）；不支持读取投票结果。
mark_read	将一条或多条消息标记为已读。
schedule_send	预约在未来某个时间发送文本或媒体（最多提前 30 天；使用 send_at 或 delay_minutes）。管控机制在预约时生效 — 对于不受信任的收件人，需先创建草稿并确认预约（包括发送时间）；发送时会占用共享速率限制器。预约会在重启后保留；仅在 serve 运行时发送（延迟不超过 15 分钟的任务会在下次启动时发送，超过此时间的任务将被丢弃）。
list_scheduled	按发送时间从近到远列出待发送的预约消息。
cancel_scheduled	取消一项待发送的预约消息 — 始终允许，因为此操作只会阻止发送。
block_contact	屏蔽联系人；始终先创建草稿，即使受信任也不会自动提交。
unblock_contact	取消屏蔽联系人；始终先创建草稿，即使受信任也不会自动提交。

每项基于 WhatsApp 数据（消息、姓名、联系人、说明文字）生成的工具结果， 都会加上明确的不可信数据横幅。应将其视为 MCP 客户端展示给你的数据， 切勿当作模型需要遵循的指令：通过 WhatsApp 收到的任何内容都无法告诉 你的助手该做什么。

发送闸门

这是 verygoodplugins/whatsapp-mcp 所不具备的部分。每项出站操作——文本、媒体、语音留言、回应、编辑、删除、投票、拉黑、解除拉黑或已读回执——都会经过同一条路径，由服务端强制执行，而不是通过提示模型“谨慎行事”：

1. 先起草。 对尚未信任的收件人调用发送工具，不会发送任何内容。你会收到一份预览（解析出的收件人姓名和 JID，以及确切的出站内容）和一个 draft_token。
2. 确认后提交。 使用该 draft_token 重新发起完全相同的调用，即会发送。草稿会在 5 分钟后过期；重新提交的内容只要有一个字节不同，令牌就会失效。
3. 审慎信任。 使用 whatsapp-connect-mcp trust --add <who> 将联系人或群组标记为可信——<who> 可以是姓名、电话号码或 JID；如果姓名有歧义，会列出匹配项并询问，而不是自行猜测——这样向其发送内容时，第一次调用就会直接提交，无须先起草。这是仅限 CLI 的开关——没有 MCP 工具可以授予信任，因此模型无法通过信任来绕过起草步骤。每次决定是否发送时都会重新读取信任列表，因此 trust --add/--remove 会立即生效，包括对已经运行的 serve 进程也是如此。如果不想长期保留某项授权，可以使用会话级形式：whatsapp-connect-mcp trust --session --add <jid> 仅在当前 serve 进程运行期间提升收件人的信任级别——绝不会写入 config.json，并会在下次启动 serve 时自动清除。当你正在与某个人或群组积极起草对话，且已手动确认首次发送时，可以使用此功能；它能省去向该收件人发送时的起草与确认往返，而无需授予永久权限。与持久信任一样，此功能仅限 CLI 使用（没有 MCP 工具可以授予此信任），并且拉黑/解除拉黑无论如何每次调用都仍须起草。
4. 始终进行速率限制。 每次发送——无论是否经过起草、收件人是否可信——都会从五个发送工具共用的速率限制器中消耗一个令牌。间隔有硬性下限 5 秒，任何配置都无法降低此下限。如果提交时受到速率限制，草稿仍然有效；限制解除后，使用相同令牌重试相同调用即可。

mark_read 是起草流程的唯一例外：已读回执并非由用户撰写的内容，因此第一次调用就会发送（仍受速率限制，也仍受闸门控制）。

发送时可以附加哪些文件

上面的闸门授权的是收件人。它并未限制发送时指定的文件，因此单靠它，经过操纵的模型就可以向你已信任的收件人附加此程序能够读取的任何内容——例如 SSH 密钥、密码库。

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

操作系统	默认发件箱
Linux	~/.config/whatsapp-connect-mcp/outbox
macOS	~/Library/Application Support/whatsapp-connect-mcp/outbox
Windows	%AppData%\whatsapp-connect-mcp\outbox

发送前请将文件移入该目录，或者在 config.json 中设置 media_roots，将允许列表扩展为绝对目录路径：

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

路径会在检查前解析，因此允许目录中的符号链接会根据其实际指向的位置来判断，而不是根据它所在的位置来判断。若发送时指定的文件位于列表之外，第一次调用就会被拒绝——此时尚未生成草稿，也不会消耗速率限制令牌——而且拒绝信息不会透露路径，与此服务返回的其他错误一样。

Agent 可以读取哪些聊天

默认情况下，连接客户端会将账户中的所有聊天都交给它。这通常超出了你的本意：你只是想让它协助处理一个群组，而不是让它长期访问十年来的所有通信记录。

因此，可以将可读取范围限制在允许列表内。setup 会询问一次，之后可通过仪表板的 客户端 选项卡或 scope 命令进行更改：

whatsapp-connect-mcp scope --list                       # what agents can read now
whatsapp-connect-mcp scope --allow [email protected]
whatsapp-connect-mcp scope --deny  [email protected]
whatsapp-connect-mcp scope --all                        # drop the limit again

--allow 不仅会指定一个聊天，还会启用限制——允许一个聊天，就意味着限制其余聊天。--all 会关闭限制，但保留列表，因此重新启用限制时无需重新输入。在仪表板中，这两种模式也并列显示，并标记当前模式，所以无论切换到哪种模式，都只需点击一次。

启用限制后，涵盖以下内容：

• 列表之外聊天中的消息、搜索、上下文、媒体和历史记录都会被拒绝——拒绝信息会说明该聊天超出范围，而不是假装它不存在，这样模型就会停止询问，而不是反复重试。
• 跨所有聊天的问题——全局搜索、poll_new_messages、通话历史记录、联系人搜索——返回的结果都会筛选为允许范围内的内容。 联系人也包括在内：如果 Agent 仍然可以遍历你的通讯录，就会泄露限制本来要保密的信息。
• 所有读取工具都通过对存储层进行一次封装来实施限制，因此当前和未来的每个读取工具都会受到涵盖。

在依赖此功能之前，有三点值得了解：

• 限制由服务端实施，而不是由各个客户端单独实施。 每个客户端都使用相同的 bearer token 进行身份验证，因此服务端无法区分 Cursor 和 Claude Desktop。它们都应用同一个范围。要实现按客户端设置范围，必须先为每个客户端配置独立的 token。
• 只有你可以更改限制。 没有 MCP 工具会写入 config.json——这与信任列表遵循的规则相同。如果范围的适用对象可以扩大范围，它就形同虚设。
• 允许列表为空，意味着无法读取任何内容，而不是可以读取所有内容。 这是 setup 第三个回答所留下的状态，而且这是有意为之：另一种解释会悄无声息地授予超出你要求的访问权限。此时所有读取工具都会返回空结果，看起来就像安装出了问题，因此 check 会指出这一状态，并说明如何退出。

仪表板不受这些限制。它是你查看自己消息的窗口，不是 Agent 的窗口。

此限制针对读取。发送操作由发送闸门单独管理，无论聊天是否可读，每个收件人都需要你确认。

与 verygoodplugins/whatsapp-mcp 的比较

目前广为人知的最佳替代方案虽然可用，但采用起来很麻烦，而且没有发送安全防护：

	verygoodplugins/whatsapp-mcp	whatsapp-connect-mcp
所需运行时	Go 和 Python，需要两个进程	单个静态二进制文件，无需任何前置条件
安装	克隆仓库、手动运行桥接程序、手动编辑客户端配置、重启	一行安装命令 → setup 向导自动注入客户端配置
配对	在需要你手动保持打开的终端中显示 QR 码	由向导管理 QR 码配对；会话由二进制文件监控
发送安全防护	无——模型可以立即发送	先起草再发送的发送闸门 + 速率限制器
提示词注入防御	无	每条源自 WhatsApp 的结果都会显示不可信数据横幅
读取范围	始终可读取所有聊天	可读取所有聊天，或在设置时选择并在之后编辑允许列表
诊断	无	doctor（CLI 子命令和 MCP 工具），输出经过净化
分发方式	仅支持 Git 克隆	GitHub Releases、安装脚本、MCP Registry、MCPB bundle、npm 封装程序

封禁风险

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

1. 客户端可被识别。 链接设备在注册时会声明自己的身份。whatsmeow 的默认设置会声明操作系统字符串为 whatsmeow，平台类型为未知，因此只需读取配对载荷，就能将其与官方客户端区分开来。本项目覆盖了这一设置，改为声明 Chrome 浏览器身份（internal/bridge/clientinfo.go），这也是手机在“已关联的设备”中为此设备显示的身份。

不要误以为这项覆盖就解决了问题。它只能绕过最简单的检查，并未解决根本问题。serve 和 setup 确实会在连接前刷新上报的 WhatsApp Web 版本，因此版本及由此得出的构建哈希会与真实发布版本保持一致，而不是使用构建时打包的版本；但用户代理仍包含 whatsmeow 的占位运营商和制造商字段，而且会话在网络上的行为表现得像 whatsmeow，而不是 Chrome。使用 whatsapp-web.js 的用户也收到了下文所述的相同警告；该工具驱动的是真正的 Chrome 浏览器，具有真实的指纹。这说明声明的身份从来都不是决定性信号。更改身份对已经配对的会话也没有作用：身份是在配对时发送的，因此现有会话会保留注册时使用的身份，直到你重新配对。

2. 行为。 据报告的触发因素，按出现频率大致排序：给从未先联系过你的人发消息、发送速度过快、配对后不久发送大量消息、重复发送相同消息、自动发布 Status，以及频繁的重连循环。

令人不安的是，公开证据表明，（1）可能才是主要因素。在 whatsmeow#810 中——这场发生于 2025 年 5 月的“你的账号可能存在风险”警告风波于 2026 年 7 月以 not planned 关闭——用户报告称，一些账号只是保持连接、处于闲置状态且从未发送过消息，也收到了警告；还有一些账号已经断开连接数周，也收到了警告。使用 whatsapp-web.js（完全不同的实现）的用户也收到了警告。同一讨论串中的一位 Baileys 维护者则持相反观点，认为这“主要是行为问题”。没有人确定究竟是哪种原因，讨论串也在没有结论的情况下关闭了。

因此：这里的发送门控和速率限制确实能缓解（2），但对（1）毫无作用。根据现有证据，良好的行为影响的是轮到你被封的时间，而不是封禁是否会发生。

配对前值得阅读的报告，附上日期以便你判断信息的新旧：

报告	创建时间	最近活动
whatsmeow#810 — “账号可能存在风险”警告风波	2025 年 5 月	2026 年 7 月（已关闭）
Baileys#2309 — 自动发布 Status 后遭永久封禁	2026 年 1 月	2026 年 5 月（仍开放）
Baileys#1869 — 运行 3 年以上的实例一周内被暂停五次	2025 年 10 月	2026 年 5 月

对于厂商博客中的封禁统计数据——“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）。
• 不支持拨出电话。 可以读取通话记录，但不支持发起通话。
• 一次只能配对一个号码。 每个号码都有各自的消息、信任列表、可读 聊天和计划任务，因此在号码之间切换很顺畅，彼此的数据也不会互相 携带。但一次只能关联一个号码——若要同时运行两个账号，且分别绑定到 不同的 MCP 客户端，则需要两个服务；目前尚不支持。
• whatsmeow 会跟进 WhatsApp 协议变更，而非反过来。WhatsApp 方面 的变更可能会导致配对或发送功能失效，直到 whatsmeow（进而本项目） 跟上更新。

数据与隐私

所有数据——会话密钥、消息、媒体、联系人、通话记录——都保存在此 程序数据目录下的本地 SQLite 数据库中。此服务不会将有关你的消息、 联系人或媒体的任何信息发送到其他地方。

除 WhatsApp 连接本身外，只有两种向外发起的网络调用。两者都会尽力 执行，超时时间均为 2 秒，且都不会携带消息内容、JID、电话号码或任何 会话凭据：

• doctor/check 会查询 GitHub 的公开发布 API，检查此程序是否有 更新版本。即使无法连接 GitHub，检查也不会阻塞或失败。
• serve 和 setup 会在连接前从 web.whatsapp.com 获取当前的 WhatsApp Web 客户端版本，确保此客户端报告的版本对应实际发布的 版本，而不是构建时打包的版本。获取失败会报告错误并忽略；即使 版本过时，仍然会连接。

数据目录：

OS	路径
Linux	~/.config/whatsapp-connect-mcp
macOS	~/Library/Application Support/whatsapp-connect-mcp
Windows	%AppData%\whatsapp-connect-mcp

在此目录中，属于 WhatsApp 账号的所有内容都保存在该账号对应的号码 目录下，属于这台机器的内容则位于顶层：

config.json              rate limits, outbox roots — shared
outbox/                  files a send may attach — shared
session.db               the current pairing
accounts/<number>/
  messages.db            that number's messages
  media/                 that number's downloaded attachments
  backups/               that number's snapshots
  account.json           that number's trust list and readable chats
  schedules.json         that number's pending scheduled sends

配对其他号码时，会为其创建独立目录；重新配对第一个号码后，其历史 记录、信任列表和设置都会与之前完全相同。现有安装会在下次运行时 调整为此目录结构，只重命名文件，不会重写文件。

诊断

whatsapp-connect-mcp check

运行与 doctor MCP 工具提供的相同检查：会话配对/连接状态、事件流 是否正常（已连接的会话如果超过 30 分钟未收到 WhatsApp 事件，就会 发出警告——此时套接字看起来正常，但消息接收已悄然停滞）、消息 数据库完整性、注入的 MCP 客户端配置、聊天范围（包括已启用但为空的 状态；此时所有读取工具都会正确返回空结果，看起来就像安装出了问题）、 数据目录权限（POSIX），以及上述版本检查。所有检查结果都经过脱敏 处理——状态行中绝不会出现 JID、电话号码、消息内容或文件系统路径； 损坏的客户端配置只会显示客户端名称，绝不会显示其磁盘路径。

仪表板

whatsapp-connect-mcp dashboard [--port n]

打印（并尝试打开）一个一次性登录链接，供与 serve --http 一同提供的小型 Web 仪表板使用。仪表板会显示连接状态、存储行数，以及 check 打印的相同诊断结果，并每隔几秒刷新一次。该链接会将 HTTP 传输现有的 bearer 令牌交换为会话 Cookie，因此无需配置或信任任何新内容。

仪表板始终只监听回环地址，与共用端口的 HTTP 传输完全相同：必须先运行 serve --http，且其他机器无法访问此页面。会话过期时（最常见的情况是服务器重启），随时可以使用 dashboard 命令重新登录——打印出的令牌绝不会写入服务器日志。

会话尚未配对时，仪表板的“配对”标签页会直接在浏览器中显示二维码。可从此处开始配对，然后用 WhatsApp 扫描：依次进入“已关联的设备”>“关联设备”，无需使用终端。WhatsApp 端登出后重新配对时，也可使用此功能。会话已配对时，同一标签页会提供“取消关联”选项：它会在 WhatsApp 服务器上将服务器登出（手机上的“已关联的设备”列表中将不再显示该设备），并重新显示二维码。终端中的 logout 命令也会执行相同操作；而 remove 只会删除本地会话，不会通知 WhatsApp。

“客户端”标签页会列出在此机器上检测到的所有 MCP 客户端——包括是否已安装、是否已添加此服务，以及配置入口所在位置——并可一键添加或移除相应配置，因此无需打开终端，就能修复诊断工具判定为损坏的配置。同一标签页还包含可读取的聊天设置，用于限制已连接的 Agent 可以读取哪些内容（参见Agent 可以读取哪些聊天）。

“信任”标签页会列出并编辑受信任联系人列表，也就是 trust 命令所管理的同一个 config.json，因此更改会立即在运行中的服务上生效。“信任”和“可读取的聊天”都接受联系人或群组的名称或电话号码，而不仅仅是原始 JID；如果名称匹配多个人，系统会列出这些人供你选择，确认前不会写入任何内容。“计划任务”标签页会列出待处理的定时发送，并允许取消。“草稿”标签页会列出 Agent 提议且正在等待处理的发送内容；批准后会按显示的确切内容发送（仍受速率限制），丢弃则会删除草稿。无论是仪表板还是 Agent 自己的重试先完成，草稿都最多只能提交一次。“备份”标签页可一键创建快照，操作与下方的 backup 命令完全相同。

备份

whatsapp-connect-mcp backup [--dest path]

将已配对账户的消息数据库写入一致性快照，保存到 <data-dir>/accounts/<number>/backups/messages-<timestamp>.db（也可通过 --dest 指定自定义路径）。每个号码都会单独备份，因此你交给他人的快照只包含该账户的数据。

备份是独立且功能完整的 SQLite 数据库，只包含消息，不包含会话或设置。与手机备份不同，在 serve 运行期间创建 backup 快照是安全的；SQLite 的 WAL 模式和忙等待超时可确保数据一致性。

消息历史是唯一无法通过其他方式恢复的内容——如有需要，会话可以重新配对，但从手机获取的消息只会在手机记得它们时保留，通常只有几个月。定期自动备份（通过 cron、systemd 定时器或 Windows 上的任务计划程序）是防止消息丢失的最简单保障。

其他命令

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 who|--remove who|--list]
whatsapp-connect-mcp scope [--allow who|--deny who|--all|--list]
                                             # limit which chats agents may read
whatsapp-connect-mcp serve [--http addr]     # run the MCP server directly (stdio by default)
whatsapp-connect-mcp service <install|uninstall|restart> [--http addr]
                                             # manage a background serve --http service (macOS/Linux/Windows)

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

更新

更新只会替换二进制文件，不会更改其他内容：配对信息、消息历史记录、信任列表和注入的客户端配置都保存在数据目录中，每次更新后都会保留。请使用安装时采用的相同方式更新——每种方式都会将新二进制文件放到旧文件所在的相同路径，因此客户端配置会继续生效：

# macOS / Linux — the install script always fetches the latest release
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

# npm global install
npm update -g whatsapp-connect-mcp

# npx without an install — @latest bypasses npx's cached copy
npx whatsapp-connect-mcp@latest setup

然后重启运行该二进制文件的程序：stdio 客户端会在 MCP 客户端下次启动会话时使用新版本（重启客户端应用）。使用 http 传输时，请重启 serve——对于通过 service install 安装的服务，请执行：

whatsapp-connect-mcp service restart

持续运行的服务不会自行重新执行，因此在重启之前，仍会由旧版本提供服务。

无需关注发布页面——whatsapp-connect-mcp check 和 doctor MCP 工具每次运行时都会将当前版本与最新发布版本进行比较；如果版本不同，还会显示两个版本号并发出警告。

卸载 / 重置

• 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。