用于 Claude Desktop 的 MCP Whatsapp

一个 模型上下文协议 (MCP) 服务器，为 Claude Desktop 提供对 WhatsApp 聊天记录和消息历史的只读访问权限。

基于 Baileys (WhatsApp Web 协议) 构建 — 无需电话号码，无需商业 API，无需云服务。一切都在您的机器上本地运行。

⚠️ 免责声明 这是一个非官方集成。WhatsApp 可能会终止使用未经授权客户端的账户。请使用辅助/测试号码，而非您的主号码。作者不对封号负责。

✨ 功能

• 🔌 本地优先 — 无外部 API，无云端

• 💾 SQLite 持久化 — 聊天记录 + 消息保存到本地数据库

• 📚 历史记录同步 — 首次配对时下载您现有的 WhatsApp 历史记录

• 🔎 搜索聊天 — 按名称、推送名称或 JID 搜索

• 📖 读取消息 — 从任何聊天中读取消息（文本、图片说明、媒体元数据）

• 🧠 Claude 原生 — 用自然语言询问 Claude Desktop

Related MCP server: WhatsApp MCP Server

🔧 可用 MCP 工具

📦 前置要求

• Node.js 18+ — 使用 node --version 检查

• Claude Desktop (macOS 或 Windows) — 下载

• 一个 WhatsApp 账户，配有一部可以扫描二维码的手机

• 推荐 macOS 或 Linux (Windows 需要调整路径)

🚀 安装

1. 克隆仓库

git clone https://github.com/danialadzhar/mcp-whatsapp.git
cd mcp-whatsapp

2. 安装依赖

npm install

如果 better-sqlite3 构建失败，请确保已安装 Xcode 命令行工具 (macOS)：xcode-select --install

🔐 首次设置 (配对 WhatsApp + 同步历史记录)

⚠️ 重要 — 请在配置 Claude Desktop 之前执行此操作。 二维码只能通过 setup.js 在终端中显示。MCP 服务器（由 Claude Desktop 启动）无法显示二维码，因为其标准输出被 MCP 协议占用。如果您跳过此步骤直接进行 Claude Desktop 配置，您的机器人将永远卡在 connecting 状态，且无法配对。

1. 运行设置脚本

node setup.js

终端中将出现一个二维码。

2. 在手机上打开 WhatsApp

• 前往 设置 → 已关联设备 → 关联新设备

• 当提示 “包含聊天记录” 或类似内容时 — 选择“是” 以下载您的历史记录

• 扫描终端中的二维码

3. 等待历史记录下载

终端将打印：

[HISTORY] chats=35 msgs=500 isLatest=false | batch #1 | DB: 35 chats, 500 messages
[HISTORY] chats=0 msgs=1200 isLatest=false | batch #2 | DB: 35 chats, 1700 messages
...

根据您的账户大小，这需要 5-30 分钟。当 30 秒内没有新批次到达时，脚本会自动检测完成。

4. 停止脚本

当您看到 HISTORY SYNC COMPLETE 和 SAFE TO EXIT 时，按 Ctrl+C。

⚙️ Claude Desktop 配置

⚠️ 与 Claude Desktop Cowork / 定时任务不兼容。 当启用 Cowork 或定时任务功能时，Claude Desktop 会为后台代理生成 多个 MCP 服务器实例。WhatsApp 一次只允许一个活跃的关联设备连接，因此重复的实例会争夺会话并导致 status=440, reconnect=true 循环。请在配置中禁用这两项（见下文第 2 步），否则此集成将无法可靠工作。

1. 找到您的 Claude Desktop 配置文件

2. 添加 MCP 服务器

打开文件并将其合并到 mcpServers 部分（如果不存在，请创建该键）：

{
  "mcpServers": {
    "whatsapp": {
      "command": "/absolute/path/to/node",
      "args": [
        "/absolute/path/to/mcp-whatsapp/mcp-server.js"
      ]
    }
  }
}

替换为您实际的路径：

• 获取 node 路径：which node (macOS/Linux) 或 where node (Windows)

• 使用绝对路径 — Claude Desktop 无法可靠地解析 shell PATH

示例（macOS，Homebrew node），已禁用 Cowork/定时任务：

{
  "mcpServers": {
    "whatsapp": {
      "command": "/opt/homebrew/bin/node",
      "args": [
        "/Users/yourname/projects/mcp-whatsapp/mcp-server.js"
      ]
    }
  },
  "preferences": {
    "coworkScheduledTasksEnabled": false,
    "ccdScheduledTasksEnabled": false
  }
}

如果您的配置中已经有 "preferences" 块，只需将两个 *ScheduledTasksEnabled 键添加到其中即可 — 不要重复该块。

3. 重启 Claude Desktop

使用 Cmd+Q 完全退出（不仅仅是关闭窗口），然后重新打开。

4. 测试

在任何 Claude Desktop 聊天中，询问：

what is my whatsapp status

Claude 将调用 whatsapp_status 工具。当出现权限提示时，请批准。

💬 示例提示词

连接后，您可以询问 Claude Desktop：

• “列出我最近的 10 个 WhatsApp 聊天”

• “在我的 WhatsApp 中搜索与 'Ahmad' 的聊天”

• “总结我与 60123456789@s.whatsapp.net 的最后 50 条消息”

• “我有多少个未读的 WhatsApp 聊天？”

• “显示每个群聊的最后一条消息”

• “查找有人提到 '会议' 的对话” (Claude 将链式调用列表 + 读取)

Claude 会根据您的问题决定调用哪些工具。

🐛 故障排除

❌ Error: Cannot find module '@whiskeysockets/baileys'

您没有安装依赖项。

cd mcp-whatsapp
npm install

❌ 日志中出现 status=440, reconnect=true 循环

两个进程正在争夺同一个 WhatsApp 会话。常见原因：

1. Claude Desktop 生成了重复的 MCP 服务器 — 在 claude_desktop_config.json 中禁用 Cowork/定时任务：

   "preferences": {
     "coworkScheduledTasksEnabled": false,
     "ccdScheduledTasksEnabled": false
   }

2. 终端脚本 + Claude Desktop 同时运行 — 终止终端进程：

   ps aux | grep "mcp-whatsapp" | grep -v grep
   kill <PID>

3. 两个 Claude Desktop 实例 — 使用 Cmd+Q 完全退出，重新打开一次。

❌ 运行 setup.js 时二维码未出现

• 确保没有其他 Node 进程占用 auth_info/：

  ps aux | grep "mcp-whatsapp" | grep -v grep

• 在运行 setup.js 之前完全退出 Claude Desktop (Cmd+Q)。

• 删除 auth_info/ 并重试：

  rm -rf auth_info
  node setup.js

❌ 工具未出现在 Claude Desktop 中

1. 验证配置 JSON 是否有效：

   # macOS
   python3 -c "import json; json.load(open('$HOME/Library/Application Support/Claude/claude_desktop_config.json'))"

2. 检查 MCP 服务器日志：

   # macOS
   tail -50 ~/Library/Logs/Claude/mcp-server-whatsapp.log

3. 验证配置中的 node 路径是否正确：

   which node

4. 完全退出并重启 Claude Desktop — 重新加载配置需要完全重启应用程序。

❌ connectionState: "connecting" 永远持续

• 会话可能已损坏。通过重新配对修复：

  # 1. Quit Claude Desktop (Cmd+Q)
  # 2. Delete auth
  rm -rf auth_info whatsapp.db
  # 3. Re-run setup
  node setup.js
  # 4. Scan QR

❌ 设置后数据库中显示 0 chats, 0 messages

• 您可能在扫描二维码时跳过了 WhatsApp 中的 “包含聊天记录” 提示。

• WhatsApp 仅在初始配对时提供历史记录同步。修复：

  rm -rf auth_info whatsapp.db
  node setup.js

  当手机询问时，选择包含历史记录。

❌ 即使配置正确，历史记录同步也从未开始

• 某些 WhatsApp 版本会跳过历史记录传输提示。解决方法：

  • 将手机上的 WhatsApp 更新到最新版本

  • 在手机上：设置 → 聊天 → 聊天记录传输（如果可用）

  • 接受以后只会捕获新消息的事实

❌ node-gyp / better-sqlite3 构建错误

• macOS: xcode-select --install

• Linux: sudo apt install build-essential python3

• Windows: 安装 windows-build-tools 或 Visual Studio Build Tools

❌ Claude Desktop 尝试调用工具时权限被拒绝

每次首次调用工具时，Claude Desktop 都会请求批准。选择 “为此任务允许” 以获得顺畅的使用体验。您也可以在 Claude Desktop 设置中按工具设置权限。

❓ 常见问题

此机器人会 24/7 捕获消息吗？

不会。MCP 服务器仅在 Claude Desktop 打开时运行。当 Claude Desktop 退出时，机器人会断开连接。

但是 — WhatsApp 会将未送达的消息排队发送到关联设备，最长可达约 14 天。当您重新打开 Claude Desktop 时，离线消息会到达并保存到数据库中。

若要实现真正的 24/7 捕获，请运行单独的后台守护进程（本仓库未包含）。

WhatsApp 会封禁我的账户吗？

任何非官方客户端都存在风险。缓解措施：

• 如果可能，请使用 辅助/测试号码

• 不要发送垃圾信息（本仓库是只读的，因此风险较低）

• 不要用于批量营销

我可以用此 MCP 发送消息吗？

此版本有意设计为 只读（更安全）。要添加发送功能，请在 mcp-server.js 中添加 whatsapp_send_message 工具 — 但要小心，MCP 触发的发送功能非常强大，可能会被提示词注入滥用。

我的数据存储在哪里？

• auth_info/ — 会话凭据（保持私密，不要共享/提交）

• whatsapp.db — 包含您的聊天记录和消息的 SQLite（保持私密）

两者均已在 gitignore 中。

如何卸载？

# Quit Claude Desktop
# Remove MCP server entry from claude_desktop_config.json
# Delete the repo folder
rm -rf mcp-whatsapp

在您的手机上：WhatsApp → 已关联设备 → 移除此设备。

多个 MCP 服务器可以共享同一个 WhatsApp 会话吗？

不能。WhatsApp 每个关联设备授权只允许一个活跃连接。运行多个 MCP 实例会导致 status=440 冲突循环。

群组怎么办？

支持群聊 — 像任何其他聊天一样列出和读取。JID 以 @g.us 结尾。

🛠 已知限制

• 与 Claude Desktop Cowork / 定时任务不兼容 — 这些功能会生成重复的 MCP 实例，从而破坏单会话 WhatsApp 连接。必须禁用（参见 Claude Desktop 配置）。

• 仅在 Claude Desktop 打开时运行 — 若要 24/7 捕获，您需要一个单独的守护进程（未包含）。

• 媒体（图片、视频、音频）未下载 — 仅文本 + 元数据。

• 回复被跟踪为单独的消息，未链接到父消息。

• 已删除的消息无法捕获。

• 历史记录同步量取决于 WhatsApp — 通常为最近 6 个月。

• 已在 macOS/Linux 上测试；Windows 路径需要在配置中调整。

• 不适用于多账户/多租户使用。

🤝 贡献

欢迎提交 Issue 和 PR。请：

• 提交带有日志的 Issue（屏蔽个人数据）

• 保持 PR 范围仅限于一个功能/修复

• 在没有周全的安全设计（权限门控、速率限制、确认 UX）的情况下，不要添加 send_message

📄 许可证

MIT © Danial Adzhar

🙏 致谢

• Baileys — 逆向工程的 WhatsApp Web 客户端

• Model Context Protocol — Anthropic 的标准

• better-sqlite3 — 快速同步 SQLite