WhatsApp MCP 服务器

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

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

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

当你将其连接到Claude时，可以执行以下操作：

若要获取此项目及其他项目的更新，请在此处输入您的电子邮件：点击这里

警告：与许多MCP服务器一样，WhatsApp MCP也受到致命三重威胁的影响。这意味着项目注入可能导致私有数据泄露。

安装

先决条件

• 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. 克隆此仓库

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

2. 运行WhatsApp桥接程序

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

   cd whatsapp-bridge
   go run main.go
   

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

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

3. 连接到MCP服务器

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

   {
     "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，路径为：

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

   对于Cursor，请将此文件保存为m- cp.json，路径为：

   ~/.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并运行应用程序

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

没有这种设置，你可能会遇到如下错误：

二进制文件是使用'CGO_ENABLED=0'编译的，go-sqlite3需要cgo才能工作。

架构概述

此应用程序由两个主要组件组成：

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

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

数据存储

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

使用方法

一旦连接，你可以通过Claude与你的WhatsApp联系人互动，利用Claude的人工智能能力在你的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：向指定的电话号码或群组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文档。文档中包含了检查日志和解决常见问题的有用提示。