WhatsApp MCP

WhatsApp MCP服务器

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

通过此功能，您可以搜索和阅读您的个人Whatsapp消息（包括图像、视频、文档和音频消息），搜索您的联系人，并向个人或组发送消息。您还可以发送媒体文件，包括图像、视频、文档和音频消息。

它连接到您的 个人WhatsApp帐户 直接通过Whatsapp网络多设备API（使用 怎么回事 图书馆）。您的所有消息都存储在本地SQLite数据库中，只有当代理通过您控制的工具访问它们时，才会发送给LLM（如Claude）。

这里有一个例子，说明当它连接到克劳德时你可以做什么。

获取我参与的此项目和其他项目的更新 在此处输入您的电子邮件

*注意：* 与许多MCP服务器一样，WhatsApp MCP受 致命的三联征这意味着项目注入可能会导致私人数据泄露。

安装

先决条件

• 去
• Python 3.6+
• 拟人克劳德桌面应用程序（或光标）
• 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

1. 运行WhatsApp桥

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

   cd whatsapp-bridge
   go run main.go

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

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

1. 连接到MCP服务器

将以下json与相应的{{PATH}}值一起复制：

   {
     "mcpServers": {
       "whatsapp": {
         "command": "{{PATH_TO_UV}}", // Run `which uv` and place the output here
         "args": [
           "--directory",
           "{{PATH_TO_SRC}}/whatsapp-mcp/whatsapp-mcp-server", // cd into the repo, run `pwd` and enter the output here + "/whatsapp-mcp-server"
           "run",
           "main.py"
         ]
       }
     }
   }

对于 克劳德，将此另存为 claude_desktop_config.json 在您的Claude Desktop配置目录中：

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

对于 光标，将此另存为 mcp.json 在Cursor配置目录中：

   ~/.cursor/mcp.json

1. 重新启动克劳德桌面/光标

打开克劳德桌面，你现在应该看到WhatsApp是一个可用的集成。

或者重新启动Cursor。

Windows兼容性

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

使其工作的步骤：

1. 安装C编译器\

我们建议使用 Msys 2 安装适用于Windows的C编译器。安装MSYS2后，请确保添加 ucrt64\bin 文件夹到您的 PATH.\ → 提供分步指南 这里.

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

   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. 去WhatsApp桥 (whatsapp-bridge/)：Go应用程序，连接到WhatsApp的web API，通过二维码处理身份验证，并将消息历史存储在SQLite中。它是WhatsApp和MCP服务器之间的桥梁。

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

数据存储

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

用法

连接后，您可以通过Claude与您的WhatsApp联系人进行交互，在您的WhatsApp对话中利用Claude的人工智能功能。

MCP工具

Claude可以访问以下工具与WhatsApp进行交互：

• search_contacts：按姓名或电话号码搜索联系人
• list_消息：使用可选筛选器和上下文检索邮件
• list_chats：列出带有元数据的可用聊天记录
• get_chat：获取特定聊天的信息
• get_direct_chat_by_contact：查找与特定联系人的直接聊天
• get_contact_chats：列出涉及特定联系人的所有聊天记录
• get_last_交互：获取联系人的最新消息
• get_message_context：检索特定消息的上下文
• send_message：向指定的电话号码或组JID发送WhatsApp消息
• send_file：将文件（图像、视频、原始音频、文档）发送给指定的收件人
• send_audio_消息：将音频文件作为WhatsApp语音消息发送（要求文件为.ogg opus文件或必须安装ffmpeg）
• 下载_媒体：从WhatsApp消息下载媒体并获取本地文件路径

媒体处理功能

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

媒体发送

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

• 图像、视频、文档：使用 send_file 共享任何支持的媒体类型的工具。
• 语音信息：使用 send_audio_message 该工具将音频文件作为可播放的WhatsApp语音消息发送。

- 为了获得最佳兼容性，音频文件应位于 .ogg Opus格式。 - 安装FFmpeg后，系统将自动将其他音频格式（MP3、WAV等）转换为所需的格式。 - 没有FFmpeg，您仍然可以使用 send_file 工具，但它们不会显示为可播放的语音消息。

媒体下载

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

技术细节

1. Claude向Python MCP服务器发送请求
2. MCP服务器向Go桥查询WhatsApp数据或直接查询SQLite数据库
3. Go访问WhatsApp API并使SQLite数据库保持最新
4. 数据通过链流回克劳德
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文件。该文档包括检查日志和解决常见问题的有用提示。