MCP 服务器

WhatsApp MCP Server

WhatsApp MCP 服务器 (WhatsApp MCP fúwùqì)

lharries

通信

访问服务器

README

WhatsApp MCP 服务器

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

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

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

以下是连接到 Claude 后您可以执行的操作示例。

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 工具发送原始音频文件。

步骤

克隆此存储库

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

运行 WhatsApp 桥

导航到 whatsapp-bridge 目录并运行 Go 应用程序：
```
cd whatsapp-bridge
go run main.go
```
首次运行时，系统将提示您扫描二维码。使用您的 WhatsApp 移动应用程序扫描二维码进行身份验证。

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

连接到 MCP 服务器

复制下面的 json，并使用适当的 {{PATH}} 值：

{
  "mcpServers": {
    "whatsapp": {
      "command": "{{PATH_TO_UV}}", // 运行 `which uv` 并将输出放在此处
      "args": [
        "--directory",
        "{{PATH_TO_SRC}}/whatsapp-mcp/whatsapp-mcp-server", // cd 进入 repo，运行 `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

重启 Claude 桌面 / Cursor

打开 Claude 桌面，您现在应该看到 WhatsApp 作为可用的集成。

或者重启 Cursor。

Windows 兼容性

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

使其工作的步骤：

安装 C 编译器
我们建议使用 MSYS2 为 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.

架构概述

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

Go WhatsApp 桥 (whatsapp-bridge/)：一个 Go 应用程序，它连接到 WhatsApp 的 Web API，通过 QR 码处理身份验证，并将消息历史记录存储在 SQLite 中。它充当 WhatsApp 和 MCP 服务器之间的桥梁。
Python MCP 服务器 (whatsapp-mcp-server/)：一个 Python 服务器，它实现了模型上下文协议 (MCP)，该协议提供了标准化工具，供 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（在打印包含 meda 的消息时显示），这将下载媒体，然后返回文件路径，然后可以打开该文件路径或将其传递给另一个工具。

技术细节

Claude 向 Python MCP 服务器发送请求
MCP 服务器向 Go 桥查询 WhatsApp 数据或直接查询 SQLite 数据库
Go 访问 WhatsApp API 并保持 SQLite 数据库最新
数据通过链返回到 Claude
发送消息时，请求从 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 桌面集成故障排除，请参阅 MCP 文档。该文档包括检查日志和解决常见问题的有用提示。