WhatsApp MCP Server

WhatsApp MCP 服务

这是一个用于 WhatsApp 的 Model Context Protocol（MCP）服务。

借助它，你可以搜索和阅读个人 WhatsApp 消息（包括图片、视频、文档和音频消息），搜索联系人，并向个人或群组发送消息。你还可以发送图片、视频、文档和音频消息等媒体文件。

它通过 WhatsApp Web 多设备 API（使用 whatsmeow 库）直接连接到你的个人 WhatsApp 账号。所有消息都会存储在本地 SQLite 数据库中，只有当 Agent 通过你控制的工具访问消息时，消息才会发送给大模型（例如 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}}", // 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，将其保存为 claude_desktop_config.json，并放在 Claude Desktop 配置目录中：

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

   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/）：一个连接到 WhatsApp Web API、通过二维码处理身份验证并将消息历史记录存储在 SQLite 中的 Go 应用。它充当 WhatsApp 与 MCP 服务之间的桥梁。

2. Python MCP 服务（whatsapp-mcp-server/）：一个实现 Model Context Protocol（MCP）的 Python 服务，为 Claude 提供标准化工具，以便与 WhatsApp 数据交互并收发消息。

数据存储

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

使用方法

连接后，你可以通过 Claude 与 WhatsApp 联系人互动，借助 Claude 的 AI 能力在 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 文档。文档包含检查日志和解决常见问题的实用建议。