whatsapp-macos

前往 https://mcp.paperknife.app/ 查看

适用于 macOS 的 WhatsApp MCP

一个将 Claude 连接到 WhatsApp 的 Model Context Protocol 服务。让 Claude 帮你了解未读聊天、搜索消息记录或发送回复。

大约一分钟即可开始读取消息，无需扫描二维码，也无需安装 Node.js。发送消息是可选功能，但需要额外一个步骤。

功能

按姓名或电话号码搜索联系人。按日期筛选聊天记录。查看最近对话及未读数量。汇总所有尚未阅读的消息。连接桥接程序后，可发送回复并接收来信。

要求

• 安装并登录了 WhatsApp 桌面应用的 macOS
• Node.js 18+，仅在需要发送消息时需要

无需安装 Python。uvx 会自行获取合适的版本。

安装

如果尚未安装，请安装 uv：

curl -LsSf https://astral.sh/uv/install.sh | sh

安装到此为止。uvx 会在首次启动时下载服务，因此无需创建虚拟环境，也无需执行 pip install。请转到下一节，配置 Claude 连接到它。

从源代码安装

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

连接到 Claude Desktop

1. 打开配置文件：

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

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

2. 查找 uvx 的完整路径：

   which uvx
   

3. 添加 WhatsApp MCP 服务，并将该路径粘贴为命令：

   {
     "mcpServers": {
       "whatsapp": {
         "command": "/Users/YOU/.local/bin/uvx",
         "args": ["whatsapp-mcp-macos"]
       }
     }
   }
   

   请使用绝对路径，不要只写 uvx。Claude Desktop 启动时使用精简的 PATH，其中不包含 ~/.local/bin，因此只写命令名称是服务未显示的最常见原因。

4. 按 Cmd+Q 退出 Claude Desktop，然后重新打开。仅关闭窗口是不够的。

5. 点击聊天输入框中的 MCP 工具图标，并确认列表中有“whatsapp”。

6. 开始聊天：

   • “显示我最近的 WhatsApp 聊天”
   • “搜索有关晚餐安排的消息”

连接到 Cursor

在项目的 .cursor/mcp.json 中添加：

{
  "mcpServers": {
    "whatsapp": {
      "command": "/Users/YOU/.local/bin/uvx",
      "args": ["whatsapp-mcp-macos"]
    }
  }
}

重启 Cursor，即可在 AI 聊天中使用 WhatsApp 工具。

用法

读取消息（立即可用）

直接向 Claude 提问：

• “显示我最近的 WhatsApp 聊天”
• “搜索关于晚餐的消息”
• “John 昨天说了什么？”
• “告诉我未读消息的内容”

发送消息（需要桥接程序）

1. 启动 WhatsApp 桥接程序：

   cd bridge && npm install && npm start
   

2. 让 Claude 检查连接：

   • “检查 WhatsApp 状态”

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

4. 连接后即可发送消息：

   • “给妈妈发消息，说我会晚点到”
   • “回复 John：‘听起来不错’”

工具

工具	描述	需要桥接程序
whatsapp_status	检查连接状态，需要时获取二维码	否
whatsapp_search_contacts	按姓名或电话号码搜索联系人	否
whatsapp_list_chats	列出最近的对话	否
whatsapp_get_messages	获取某个聊天中的消息	否
whatsapp_search_messages	搜索所有聊天中的消息	否
whatsapp_unread	获取未读消息摘要	否
whatsapp_send	发送消息	是
whatsapp_incoming	获取实时来信	是

工作原理

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