适用于 macOS 的 WhatsApp MCP

一个将 Claude 连接到你的 WhatsApp 的 模型上下文协议 (Model Context Protocol) 服务器。通过自然对话即可读取消息、搜索联系人、发送回复。

功能

• 搜索联系人 — 通过姓名或电话号码查找任何人

• 读取消息 — 获取带有日期过滤和搜索功能的聊天记录

• 列出聊天 — 查看带有未读计数的近期对话

• 发送消息 — 直接通过 Claude 回复（需 QR 码验证）

• 实时接收 — 在消息到达时获取通知

要求

• macOS，且已安装并登录 WhatsApp 桌面版应用

• Python 3.10+

• Node.js 18+（用于发送消息）

安装

使用 pip

pip install whatsapp-mcp-macos

从源码安装

git clone https://github.com/kalki-kgp/whatsapp-mcp.git
cd whatsapp-mcp
pip install -e .

连接到 Claude Desktop

1. 打开配置文件：

   open ~/Library/Application\ Support/Claude/claude_desktop_config.json

   如果文件不存在，请创建它。

2. 添加 WhatsApp MCP 服务器：

   {
     "mcpServers": {
       "whatsapp": {
         "command": "python3",
         "args": ["-m", "whatsapp_mcp"]
       }
     }
   }

3. 重启 Claude Desktop（Cmd+Q，然后重新打开）

4. 在聊天输入框中查找 MCP 工具图标 (🔨) — 点击它以验证是否列出了 "whatsapp"

5. 开始聊天：

   • "Show my recent WhatsApp chats" (显示我最近的 WhatsApp 聊天)

   • "Search messages for dinner plans" (搜索关于晚餐计划的消息)

连接到 Cursor

添加到项目中 .cursor/mcp.json：

{
  "mcpServers": {
    "whatsapp": {
      "command": "python3",
      "args": ["-m", "whatsapp_mcp"]
    }
  }
}

重启 Cursor 并在 AI 聊天中使用 WhatsApp 工具。

使用方法

读取消息（立即生效）

只需询问 Claude：

• "Show my recent WhatsApp chats" (显示我最近的 WhatsApp 聊天)

• "Search for messages about dinner" (搜索关于晚餐的消息)

• "What did John say yesterday?" (John 昨天说了什么？)

• "Catch me up on unread messages" (帮我查看未读消息)

发送消息（需要桥接）

1. 启动 WhatsApp 桥接：

   cd bridge && npm install && npm start

2. 让 Claude 检查连接：

   • "Check WhatsApp status" (检查 WhatsApp 状态)

3. 如果显示 QR 码，请在浏览器中打开数据 URL 并用手机扫描

4. 连接后，你可以发送：

   • "Send a message to Mom saying I'll be late" (给妈妈发消息说我会迟到)

   • "Reply to John with 'sounds good'" (回复 John 说 'sounds good')

工具

工作原理

Claude ──MCP──▶ WhatsApp MCP Server
                       │
                       ├──▶ Local SQLite DBs (read messages)
                       │    ~/Library/Group Containers/group.net.whatsapp.WhatsApp.shared/
                       │
                       └──▶ WhatsApp Bridge (:3010) ──▶ WhatsApp Web
                            (for sending)

读取操作直接查询本地 WhatsApp 数据库 — 速度快且可离线工作。

发送操作通过桥接程序进行，该程序使用 Baileys 连接到 WhatsApp Web。

开发

# Clone
git clone https://github.com/kalki-kgp/whatsapp-mcp.git
cd whatsapp-mcp

# Install in dev mode
pip install -e ".[dev]"

# Run server
python -m whatsapp_mcp

隐私

• 所有数据保留在本地 — 消息是从你自己的 WhatsApp 数据库中读取的

• 不会向外部服务器发送任何数据（发送时连接 WhatsApp Web 除外）

• MCP 服务器在你的机器上本地运行

许可证

MIT