WhatsApp MCP 服务器

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

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

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

以下是连接到 Claude 后可以实现的一个示例。

如需获取此项目及其他我正在开发的项目的更新，请在此处输入您的电子邮箱：点击此处

注意: 与许多 MCP 服务器一样，WhatsApp MCP 也受到 致命三重奏 的影响。这意味着项目注入可能导致私人数据外泄。

安装

先决条件

• Go
• Python 3.6+
• Anthropic Claude Desktop 应用程序（或 Cursor）
• UV（Python 包管理器），可通过 curl -LsSf https://astral.sh/uv/install.sh | sh 进行安装
• FFmpeg（可选）——仅在处理语音消息时需要。如果你想将音频文件作为可播放的 WhatsApp 语音消息发送，它们必须是 .ogg Opus 格式。如果已安装 FFmpeg，MCP 服务器会自动将非 Opus 格式的音频文件转换为 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，放置于 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/)：一个 Go 应用程序，用于连接 WhatsApp 的 Web API，通过二维码处理身份验证，并将消息历史存储在 SQLite 数据库中。它是 WhatsApp 和 MCP 服务器之间的桥梁。

2. Python MCP 服务器 (whatsapp-mcp-server/)：一个 Python 服务器，实现了模型上下文协议 (MCP)，为 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 文档。该文档提供了查看日志和解决常见问题的实用建议。

WhatsApp MCP 快速上手指南

WhatsApp MCP 是一个基于 Model Context Protocol (MCP) 的服务器，允许 AI 助手（如 Claude 或 Cursor）直接读取和发送你的个人 WhatsApp 消息、搜索联系人以及处理多媒体文件。所有数据存储在本地 SQLite 数据库中，确保隐私可控。

环境准备

在开始之前，请确保你的系统满足以下要求：

• 操作系统: macOS, Linux 或 Windows (Windows 需额外配置，见下文说明)。
• Go 语言环境: 用于运行 WhatsApp 桥接服务。
• Python 3.6+: 用于运行 MCP 服务器。
• UV 包管理器: Python 依赖管理工具。
  • 安装命令：curl -LsSf https://astral.sh/uv/install.sh | sh
  • 国内加速提示：如果上述脚本下载缓慢，可尝试手动下载二进制文件或使用国内镜像源配置 pip/uv。
• FFmpeg (可选): 仅当你需要发送可播放的 WhatsApp 语音消息（.ogg Opus 格式）时需要。若未安装，仍可发送原始音频文件。
• 客户端: Anthropic Claude Desktop 应用 或 Cursor 编辑器。

注意 (Windows 用户): Windows 默认禁用 CGO，而 go-sqlite3 需要它。你需要：

1. 安装 C 编译器（推荐 MSYS2 并添加 ucrt64\bin 到 PATH）。
2. 在运行桥接服务前执行：go env -w CGO_ENABLED=1。

安装步骤

1. 克隆项目仓库

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

2. 运行 WhatsApp 桥接服务 (Go)

进入桥接目录并启动服务。首次运行时会生成二维码，请使用手机 WhatsApp 扫描以完成认证。

cd whatsapp-bridge
go run main.go

认证后，消息历史将同步至本地 whatsapp-bridge/store/ 目录下的 SQLite 数据库。会话有效期约为 20 天，过期需重新扫码。

3. 配置 MCP 服务器

获取 uv 和项目源码的绝对路径：

• 运行 which uv 获取 UV 路径。
• 在项目根目录运行 pwd，并在结果后追加 /whatsapp-mcp-server 获取服务器路径。

根据你的客户端，创建或编辑配置文件：

选项 A: Claude Desktop

编辑文件 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 或对应 Windows 路径：

{
  "mcpServers": {
    "whatsapp": {
      "command": "{{PATH_TO_UV}}", 
      "args": [
        "--directory",
        "{{PATH_TO_SRC}}/whatsapp-mcp/whatsapp-mcp-server",
        "run",
        "main.py"
      ]
    }
  }
}

(请将 {{PATH_TO_UV}} 和 {{PATH_TO_SRC}} 替换为实际路径)

选项 B: Cursor

编辑文件 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "whatsapp": {
      "command": "{{PATH_TO_UV}}",
      "args": [
        "--directory",
        "{{PATH_TO_SRC}}/whatsapp-mcp/whatsapp-mcp-server",
        "run",
        "main.py"
      ]
    }
  }
}

4. 重启客户端

完全关闭并重新启动 Claude Desktop 或 Cursor。连接成功后，你将看到 WhatsApp 集成已就绪。

基本使用

配置完成后，你可以在聊天窗口中直接让 AI 操作 WhatsApp。以下是几个最简单的使用示例：

1. 搜索联系人

"帮我搜索名字叫 'Alice' 的联系人。" (底层调用 search_contacts 工具)

2. 查看最近消息

"列出我和 'Alice' 最近的 5 条消息。" (底层调用 list_messages 或 get_last_interaction 工具)

3. 发送文本消息

"给 'Alice' 发一条消息：'今晚八点开会，请准时参加。'" (底层调用 send_message 工具)

4. 发送图片

"把桌面上的 report.png 发送给 '项目组' 群组。" (底层调用 send_file 工具)

5. 下载媒体文件

"下载刚才那条消息里的视频文件到本地。" (底层调用 download_media 工具，返回本地文件路径)

通过以上工具，你可以充分利用 AI 的能力来管理和交互你的 WhatsApp 对话。