wazap-mcp

██╗    ██╗ █████╗ ███████╗ █████╗ ██████╗
██║    ██║██╔══██╗╚══███╔╝██╔══██╗██╔══██╗
██║ █╗ ██║███████║  ███╔╝ ███████║██████╔╝
██║███╗██║██╔══██║ ███╔╝  ██╔══██║██╔═══╝
╚███╔███╔╝██║  ██║███████╗██║  ██║██║
 ╚══╝╚══╝ ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═╝

为你的 AI 智能体准备的 WhatsApp。 这是一款 MCP 服务器，把你的 WhatsApp 账号——聊天、消息、媒体、联系人、群组——封装成 22 个工具，任何 MCP 客户端都能调用。配对码登录，无需浏览器，不依赖号码转售商，占用约 20 MB 内存。

它基于 Baileys 构建，Baileys 通过 WebSocket 对接 WhatsApp 的多设备协议。

快速开始

npm 包名为 wazap-mcp；它安装后提供的命令是 wazap。

npx wazap-mcp setup

这就是整个安装过程。它会关联你的账号、找到这台机器上已安装的 MCP 客户端、写入它们的配置，并告诉你需要重启什么。

也可以让你的智能体来做。把这段内容粘贴给它：

帮我设置好 WhatsApp：运行 npx wazap-mcp setup --agent，并按它打印的内容执行。

然后问你的智能体：“我今天在 WhatsApp 上错过了什么？”

下面是 setup 为你执行的步骤。如果你想手动运行，每一步也都可以作为单独的命令执行。

npx wazap-mcp login 会显示一个二维码；从 设置 → 已关联的设备 → 关联设备 中扫描即可。手边没有摄像头，或者通过 SSH 远程关联？运行 npx wazap-mcp login --phone +15550100 会打印一个 8 位字符的代码，你在 改用手机号关联 下输入它即可。最后它会询问是否允许智能体发送消息；除非你说“是”，否则答案就是“否”。以后可以通过 npx wazap-mcp config writes on 更改这一设置。

npx wazap-mcp connect claude-code 为一个客户端写入 MCP 配置项。连接客户端 这一节的表格列出了其余客户端的写法。

单独运行 npx wazap-mcp 是安全的：它会打印你当前的状况和下一步该做什么，并且不会启动任何服务器。当有什么不对劲时，第一个要运行的是 npx wazap-mcp status——它会检查 Node、数据目录、锁文件、凭据以及是否有新版本，并能在任何有问题的地方旁边打印修复方法。

连接客户端

wazap connect <client> 为你写入配置项，同时保留文件中的其他内容，并且在第一次更改前备份一次。--dry-run 可以预览将要写入的内容。

任何 MCP 客户端的用法都一样：命令是 npx -y wazap-mcp，传输方式为 stdio。告诉智能体先调用 learn——它会返回 id 格式、所有工作流以及每个错误代码的处理方法。

{
  "mcpServers": {
    "whatsapp": {
      "command": "npx",
      "args": ["-y", "wazap-mcp"]
    }
  }
}

Claude Desktop、Cursor 和 Gemini CLI 接受的正是上面的格式。VS Code 把配置嵌套在 servers 下，并且要求在 command 旁边有一个 "type": "stdio"。Codex CLI 则使用 TOML：

[mcp_servers.whatsapp]
command = "npx"
args = ["-y", "wazap-mcp"]

skills/ 文件夹遵循 Agent Skills 格式，因此 Codex、Cursor 以及其他支持技能的智能体都能加载相同的五个技能。

Related MCP server: wa-bridge

工具

每条消息都会返回一个非空的 text 字段：媒体和系统消息会带有占位符，比如 [image] 说明文字、[voice message]、[deleted] 或 [poll] Pizza or pasta?。时间戳采用 ISO 8601 格式并带上设备的 UTC 偏移量，同时提供人类可读的 age，例如 2h ago。

技能

wazap 附带五个 Agent Skills（智能体技能），它们教会智能体的不只是工具本身，还有工具背后的工作流程：

把它们（服务器和技能）作为一个 Claude Code 插件整体安装：

/plugin marketplace add razvangirgiz/wazap
/plugin install wazap@wazap

也可以把 skills/<name>/ 复制进你的智能体读取的任意技能目录。

错误

每次失败返回的都是结构化的 { error, message, fix }，而不是堆栈，这样智能体可以决定直接重试、询问用户，还是停止。

数据目录

所有内容都位于 ~/.wazap（可通过 --data-dir 或 WAZAP_DATA_DIR 覆盖），目录以 0700 权限创建，凭据文件以 0600 权限写入：

~/.wazap/
  auth/         WhatsApp credentials — treat this like a password
  media/        downloads from download_media
  history/      per-chat message history, so a restart is not amnesia
  store.json    chat-list snapshot
  server.lock   pid of the running server
  daemon.json   loopback endpoint a second wazap bridges to
  .env          optional settings, see .env.example

凭据写入会先写到一个临时文件，再重命名到最终位置，因此即使在写入过程中杀掉进程，也不会导致你重新关联手机。

同时使用多个客户端

Claude Desktop、Claude Code 和 Cursor 各自启动自己的 wazap。WhatsApp 允许每个关联设备只使用一个套接字，因此它们共享一个会话，而不是互相争抢。数据目录中的第一个 wazap 拥有该会话，并在 127.0.0.1 上打开一个 MCP 端点；之后启动的每个 wazap 都通过该端点桥接到它。无需任何配置，客户端也察觉不出区别。拥有者会发布 <data-dir>/daemon.json（0600），其中包含其 pid、端口以及桥接器认证时使用的令牌。

桥接器所提供的内容完全取决于拥有者所暴露的内容，因此，如果拥有者以 --read-only 启动，那么所有客户端都会处于只读状态，无论这些客户端以什么标志启动。

当拥有者退出时，桥接器也随之退出，客户端下次启动的 wazap 会成为新的拥有者。

WAZAP_NO_SHARE=1 可退出共享：同一目录下的第二个 wazap 会以退出码 2 退出，并指明已在运行的实例的 pid。显式指定 --http 时它是独立服务器，而不是桥接器，并且会以同样方式被拒绝。

只读模式

写入功能需要主动开启。login 会询问一次，并将答案存储到 <data-dir>/.env；wazapconfig writes on|off 可更改此设置，而单独运行 wazap config 会列出所有生效的设置及其来源。

WAZAP_READ_ONLY=1 或 wazap serve --read-only 会完全不注册写入工具。Agent 永远不会看到这些工具，因此即使误操作也无法用你的号码给任何人发消息——当绑定的是你的个人账号时，这一点非常有用。

写入操作同样受速率限制，为 WAZAP_RATE_LIMIT 次/分钟（默认 20，0 表示禁用）。发送速度超过人类正常水平正是账号被封禁的原因。

HTTP 模式

WAZAP_READ_TOKEN=$(openssl rand -hex 32) \
WAZAP_WRITE_TOKEN=$(openssl rand -hex 32) \
npx wazap-mcp serve --http --host 0.0.0.0 --port 8766

在 /mcp 上提供流式 HTTP，并在 /healthz 提供健康检查。有两种 载体令牌：读取令牌能获取只读工具，写入令牌还会解锁写入工具，因此泄露的读取令牌永远无法给任何人发消息。没有读取令牌时，refuses 拒绝绑定非回环地址。

自托管

当 Agent 不在你的笔记本电脑上时，可以在自己的服务器上运行 whathost：另一台机器、VPS 或客户的基础设施。会话保持在该服务器上，数据不会经过任何第三方。

使用 systemd

npm install -g wazap-mcp
sudo useradd --system --home /var/lib/wazap --create-home wazap
sudo -u wazap WAZAP_DATA_DIR=/var/lib/wazap wazap login --phone +15550100   # pairing code works over SSH
sudo -u wazap tee /var/lib/wazap/.env >/dev/null <<END
WAZAP_READ_TOKEN=$(openssl rand -hex 32)
WAZAP_WRITE_TOKEN=$(openssl rand -hex 32)
END
sudo curl -fsSL https://raw.githubusercontent.com/razvangirgiz/wazap/main/deploy/wazap.service -o /etc/systemd/system/wazap.service
sudo systemctl enable --now wazap
curl -s http://127.0.0.1:8766/healthz

该服务单元只绑定环回地址。先用两行的 deploy/Caddyfile（编辑主机名后运行 caddy run --config deploy/Caddyfile）或任何反向代理在前面终结 TLS，然后将客户端指向 https://your-host/mcp，并携带 Authorization: Bearer <read or write token>。

使用 Docker

git clone https://github.com/razvangirgiz/wazap && cd wazap
printf 'WAZAP_READ_TOKEN=%s\nWAZAP_WRITE_TOKEN=%s\n' $(openssl rand -hex 32) $(openssl rand -hex 32) > .env
docker compose run --rm wazap login --phone +15550100   # once; the session lands in the wazap-data volume
docker compose up -d
curl -s http://127.0.0.1:8766/healthz

容器只在环回地址上发布 8766 端口；把同样的 TLS 代理放在主机前面。升级方式是 git pull && docker compose up -d --build；回滚会保持会话。

哪些客户端可以连接

Claude Code、Claude Desktop、Cursor、Codex、VS Code 以及任何带有 “MCP URL + header” 字段的客户端，都可以使用 Bearer 令牌进行连接。claude.ai Connectors 需要 OAuth 而不是静态令牌，因此它们暂时还不能使用自托管的 wiled。在只需要读取的客户端中保留读取令牌；而要将写入令牌有意地分发给需要它的客户端。

设置

命令行标志优先于环境变量，环境变量优先于 <data-dir>/.env。

已知限制

• 非官方。 Baileys 对 WhatsApp 的多设备协议进行了逆向工程。它不是 WhatsApp Business API，Meta 也不提供支持。

• 封禁风险是真实存在的。 自动发送、群发消息或任何不像人类会操作的行为都可能使该号码被封禁，并且在这边无法恢复。限制速率会有帮助，并提供是保障。

• 媒体密钥会过期。 WhatsApp 会从服务器移除较旧的附件，因此对旧消息执行 download_media 会返回 MEDIA_UNAVAILABLE。

• 历史记录取决于手机同步。 设备的同步。 wazap 看到的是 WhatsApp 提供给关联设备的历史记录，而您手机上的完整存档。带 before 参数的 read_messages 会尽量请求更多历史，但受限于 WhatsApp 保留内容。

• @lid IDs 新账号以隐私 ID 而非手机号来区分。wizard 在学会映射后会将其还原为手机号，否则会原封不动地透过 @lid。

• 手机必须保持可达。 手机关机达到一段时间后，关联设备会停止接收消息；get_status 会在 hint 中说明这一点。

开发

npm install
npm run typecheck
npm test                       # builds, then runs node --test
node test/smoke-stdio.mjs      # drives the built binary over MCP stdio
npm run dev -- status          # run from source with tsx

npm test 不需要 WhatsApp 会话。stdio 冒烟测试会在一个无线数据技术人员入手尼不可预定的重用数临时目录中启动构造出的二进制文件，并检查 unlinked 安装仍然能响应 initialize、tools/list 和 get_status。

采用 MIT 许可证。