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语音消息发送，它们必须在
.oggOpus格式。安装FFmpeg后，MCP服务器将自动转换非Opus音频文件。没有FFmpeg，您仍然可以使用send_file工具。
步骤
- 克隆此存储库
git clone https://github.com/lharries/whatsapp-mcp.git
cd whatsapp-mcp- 运行WhatsApp桥
导航到whatsapp桥目录并运行Go应用程序：
cd whatsapp-bridge
go run main.go第一次运行它时，系统会提示您扫描二维码。使用WhatsApp移动应用程序扫描二维码进行身份验证。
大约20天后，您可能需要重新进行身份验证。
- 连接到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- 重新启动克劳德桌面/光标
打开克劳德桌面，你现在应该看到WhatsApp是一个可用的集成。
或者重新启动Cursor。
Windows兼容性
如果您在Windows上运行此项目，请注意 go-sqlite3 需要 CGO将启用 以便编译和正常工作。默认情况下， CGO在Windows上已禁用，因此您需要显式启用它并安装C编译器。
使其工作的步骤：
- 安装C编译器\
我们建议使用 Msys 2 安装适用于Windows的C编译器。安装MSYS2后，请确保添加 ucrt64\bin 文件夹到您的 PATH.\ → 提供分步指南 这里.
- 启用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.架构概述
此应用程序由两个主要组件组成：
- 去WhatsApp桥 (
whatsapp-bridge/)：Go应用程序，连接到WhatsApp的web API，通过二维码处理身份验证，并将消息历史存储在SQLite中。它是WhatsApp和MCP服务器之间的桥梁。
- 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的消息时显示），这会下载媒体，然后返回文件路径，然后可以打开或传递给另一个工具。
技术细节
- Claude向Python MCP服务器发送请求
- MCP服务器向Go桥查询WhatsApp数据或直接查询SQLite数据库
- Go访问WhatsApp API并使SQLite数据库保持最新
- 数据通过链流回克劳德
- 发送消息时，请求从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文件。该文档包括检查日志和解决常见问题的有用提示。