WhatsApp MCP 服务器

这是一个用于 WhatsApp 的模型上下文协议（MCP）服务器。

通过这个工具，您可以搜索和阅读您的个人 WhatsApp 消息（包括图片、视频、文档和音频消息），搜索联系人并向个人或群组发送消息。您还可以发送媒体文件，包括图片、视频、文档和音频消息。

它直接通过 WhatsApp Web 多设备 API 连接到您的个人 WhatsApp 账户（使用 whatsmeow 库）。所有消息都本地存储在 SQLite 数据库中，并且只有当代理通过工具访问时才会发送给 LLM（例如 Claude）。

这是连接到 Claude 后可以执行的一些操作示例。

要获取此项目及其他我正在工作的项目的更新，请在此输入您的电子邮件

安装

前提条件

• Go
• Python 3.6+
• Anthropic Claude 桌面应用程序（或 Cursor）
• UV（Python 包管理器），使用 curl -LsSf https://astral.sh/uv/install.sh | sh 安装
• FFmpeg (可选) - 仅在需要处理音频消息时才需要。如果您想将音频文件作为可播放的 WhatsApp 语音消息发送，它们必须是 .ogg Opus 格式。安装了 FFmpeg 后，MCP 服务器会自动转换非 Opus 音频文件。没有 FFmpeg，您仍然可以使用 send_file 工具发送原始音频文件。

步骤

1. 克隆此仓库

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

2. 运行 WhatsApp 桥接

   导航到 whatsapp-bridge 目录并运行 Go 应用程序：

   bash
   cd whatsapp-bridge
   go run main.go

   第一次运行时，系统会提示您扫描一个二维码。使用您的 WhatsApp 移动应用扫描该二维码以进行身份验证。

   大约 20 天后，您可能需要重新进行身份验证。

3. 连接到 MCP 服务器

   复制以下 JSON 并填写适当的 {{PATH}} 值：

   json
   {
   "mcpServers": {
   "whatsapp": {
   "command": "{{PATH_TO_UV}}", // 运行 which uv 并将输出放在这里
   "args": [
   "--directory",
   "{{PATH_TO_SRC}}/whatsapp-mcp/whatsapp-mcp-server", // 进入仓库目录，运行 pwd 并将输出加上 "/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

4. 重启 Claude Desktop / Cursor

   打开 Claude Desktop，您现在应该可以看到 WhatsApp 作为一个可用的集成。

   或者重启 Cursor。

Windows 兼容性

如果您在 Windows 上运行此项目，请注意 go-sqlite3 需要启用 CGO 才能正确编译和工作。默认情况下，Windows 上禁用了 CGO，因此您需要显式启用它并安装 C 编译器。

使其正常工作的步骤：

1. 安装 C 编译器
   我们建议使用 MSYS2 来安装适用于 Windows 的 C 编译器。安装 MSYS2 后，确保将 ucrt64\bin 文件夹添加到您的 PATH 中。
   → 详细的分步指南请参阅 这里。

2. 启用 CGO 并运行应用程序

   bash
   cd whatsapp-bridge
   go env -w CGO_ENABLED=1
   go run main.go

如果没有进行这些设置，您可能会遇到类似以下错误：

Binary was compiled with 'CGO_ENABLED=0', go-sqlite3 requires cgo to work.

架构概述

此应用程序由两个主要组件组成：1. Go WhatsApp 桥接 (whatsapp-bridge/): 一个 Go 应用程序，连接到 WhatsApp 的 Web API，通过二维码处理身份验证，并将消息历史记录存储在 SQLite 中。它充当 WhatsApp 和 MCP 服务器之间的桥梁。

1. Python MCP 服务器 (whatsapp-mcp-server/): 一个实现模型上下文协议 (MCP) 的 Python 服务器，为 Claude 提供与 WhatsApp 数据交互并发送/接收消息的标准工具。

数据存储

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

使用方法

一旦连接成功，您可以通过 Claude 与您的 WhatsApp 联系人进行互动，在 WhatsApp 对话中利用 Claude 的 AI 功能。

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: 向指定电话号码或群组 JID 发送 WhatsApp 消息
• send_file: 向指定收件人发送文件（图片、视频、原始音频、文档）
• send_audio_message: 作为 WhatsApp 语音消息发送音频文件（需要文件是 .ogg Opus 格式或已安装 ffmpeg）
• download_media: 从 WhatsApp 消息下载媒体并获取本地文件路径

媒体处理功能

MCP 服务器支持发送和接收各种媒体类型：

媒体发送

您可以向您的 WhatsApp 联系人发送各种媒体类型：

• 图片、视频、文档: 使用 send_file 工具分享任何受支持的媒体类型。
• 语音消息: 使用 send_audio_message 工具将音频文件作为可播放的 WhatsApp 语音消息发送。
  • 为了获得最佳兼容性，音频文件应为 .ogg Opus 格式。
  • 如果安装了 FFmpeg，系统会自动将其他音频格式（MP3、WAV 等）转换为所需的格式。
  • 如果没有 FFmpeg，您仍然可以使用 send_file 工具发送原始音频文件，但它们不会显示为可播放的语音消息。

媒体下载

默认情况下，仅媒体的元数据存储在本地数据库中。消息将指示已发送媒体。要访问此媒体，您需要使用 download_media 工具，该工具接受 message_id 和 chat_jid（在打印包含媒体的消息时会显示），这将下载媒体并返回文件路径，然后可以打开或传递给另一个工具。

技术细节

1. Claude 向 Python MCP 服务器发送请求
2. MCP 服务器查询 Go 桥接以获取 WhatsApp 数据或直接查询 SQLite 数据库
3. Go 访问 WhatsApp API 并保持 SQLite 数据库更新
4. 数据通过链路回流到 Claude
5. 发送消息时，请求从 Claude 流经 MCP 服务器到 Go 桥接再到 WhatsApp

故障排除

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

身份验证问题

• 二维码未显示: 如果二维码未出现，请尝试重新启动身份验证脚本。如果问题仍然存在，请检查您的终端是否支持显示二维码。- WhatsApp 已登录: 如果您的会话已经处于活动状态，Go 桥接将自动重新连接而不会显示二维码。
• 设备数量已达上限: WhatsApp 限制了关联设备的数量。如果您达到了这个限制，您需要在手机上的 WhatsApp 中移除一个现有的设备（设置 > 关联设备）。
• 消息未加载: 在初次认证后，您的消息历史可能需要几分钟才能加载完成，特别是当您有很多聊天记录时。
• WhatsApp 同步不同步: 如果您的 WhatsApp 消息与桥接不同步，请删除两个数据库文件 (whatsapp-bridge/store/messages.db 和 whatsapp-bridge/store/whatsapp.db) 并重启桥接以重新认证。

有关 Claude Desktop 集成的其他故障排除信息，请参阅 MCP 文档。该文档包括检查日志和解决常见问题的有用提示。