AI导哈

WhatsApp消息协议服务器

一个通过WhatsApp Web API连接个人账户的MCP服务器，支持消息搜索、发送及媒体文件管理，数据存储在本地SQLite数据库。

  • by gabrielstrob
  • Go
  • 本地部署
  • 更新于
在 GitHub 查看 gabrielstrob/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

  2. 运行WhatsApp桥

    导航到whatsapp桥目录并运行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_desktop_config.json 在您的Claude Desktop配置目录中：

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

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

    ~/.cursor/mcp.json

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

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

    或者重新启动Cursor。

Windows兼容性

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

使其工作的步骤：

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

  2. 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文件。该文档包括检查日志和解决常见问题的有用提示。

相关 MCP