WhatsApp MCP Server：连接Claude管理个人消息的AI工具

WhatsApp MCP Server是一个用于 WhatsApp 的模型上下文协议（MCP）服务器，你可以搜索个人 WhatsApp 消息、查找联系人并向个人或群组发送消息，通过 WhatsApp Web 多设备 API 直接连接到你的个人 WhatsApp 账户（使用 whatsmeow 库），所有消息都存储在本地 SQLite 数据库中，只有在代理通过工具访问它们时才会发送给大型语言模型（如 Claude）。

安装条件

• Python 3.6 或更高版本

• Anthropic Claude 桌面应用程序（或 Cursor）

• UV（Python 包管理器），使用以下命令安装：

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

安装步骤

1、克隆仓库：

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

2、运行 WhatsApp 桥接：

cd whatsapp-bridge
go run main.go

首次运行时，系统会提示你扫描二维码进行身份验证，使用 WhatsApp 移动应用程序扫描二维码进行认证，大约 20 天后，你可能需要重新认证。

3、连接到 MCP 服务器

复制以下 JSON 替换适当的 {{PATH}} 值：

{
  "mcpServers": {
    "whatsapp": {
      "command": " {{PATH}}/.local/bin/uv ", 
      "args": [
        " --directory ", 
        " {{PATH}}/whatsapp-mcp/whatsapp-mcp-server ", 
        " run ", 
        " main.py "
      ]
    }
  }
}

对于 Claude，将其保存为 claude_desktop_config.json，位于 Claude 桌面配置目录：

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

对于 Cursor，将其保存为 mcp.json，位于 Cursor 配置目录：

~/.cursor/mcp.json

重启 Claude 桌面或 Cursor，打开 Claude 桌面后，你应该能看到 WhatsApp 作为一个可用的集成选项，或者重启 Cursor。

架构

WhatsApp MCP Server由两个主要组件组成：

• Go WhatsApp 桥接（whatsapp-bridge/）：一个 Go 应用程序，连接到 WhatsApp 的 Web API，通过二维码进行身份验证，将消息历史存储在 SQLite 数据库中，是 WhatsApp 和 MCP 服务器之间的桥梁。

• Python MCP 服务器（whatsapp-mcp-server/）：一个实现模型上下文协议（MCP）的 Python 服务器，为 Claude 提供标准化的工具，以交互 WhatsApp 数据和发送/接收消息。

数据存储

所有消息历史都存储在 whatsapp-bridge/store/ 目录中的 SQLite 数据库中，数据库维护聊天和消息的表，消息被索引以实现高效的搜索和检索。

使用方法

一旦连接，你可以通过 Claude 与 WhatsApp 联系人互动，利用 Claude 的 AI 能力在 WhatsApp 对话中。

MCP 工具

Claude 可以访问以下工具来与 WhatsApp 互动：

• search_contacts：通过名称或电话号码搜索联系人。

• list_messages：检索消息，可选过滤器和上下文。

• list_chats：列出可用聊天及其元数据。

• get_chat：获取特定聊天的信息。

• get_direct_chat_by_contact：查找与特定联系人的直接聊天。

• get_contact_chats：列出涉及特定联系人的所有聊天。

• get_last_interaction：获取与联系人的最新消息。

• get_message_context：检索特定消息的上下文。

• send_message：向指定电话号码发送 WhatsApp 消息。

技术细节

Claude 向 Python MCP 服务器发送请求，MCP 服务器查询 Go 桥接以获取 WhatsApp 数据或直接查询 SQLite 数据库，Go 访问 WhatsApp API 保持 SQLite 数据库更新，数据通过链条返回给 Claude，发送消息时，请求从 Claude 通过 MCP 服务器到 Go 桥接再到 WhatsApp。

常见问题

如果在运行 uv 时遇到权限问题，可能需要将其添加到 PATH 或使用完整路径执行可执行文件。确保 Go 应用程序和 Python 服务器都在运行。

• QR 代码不显示：如果 QR 代码不出现，尝试重新启动身份验证脚本。如果问题仍然存在，请检查终端是否支持显示 QR 代码。

• WhatsApp 已登录：如果会话已经激活，Go 桥接将自动重新连接而不显示 QR 代码。

• 设备限制达到：WhatsApp 限制了链接设备的数量，如果达到此限制，你需要在手机上的 WhatsApp（设置 > 链接设备）中删除一个现有设备。

• 没有加载消息：初始身份验证后，可能需要几分钟才能加载消息历史，特别是如果你有很多聊天。

• WhatsApp 不同步：如果 WhatsApp 消息与桥接不同步，删除两个数据库文件（whatsapp-bridge/store/messages.db 和 whatsapp-bridge/store/whatsapp.db），重新启动桥接以重新认证。有关 Claude 桌面集成的更多故障排除信息，请参阅 MCP 文档，文档包括检查日志和解决常见问题的一些有用提示。