AI导哈

WhatsApp消息管理服务

通过WhatsApp Web API连接个人账户，实现消息搜索、联系人管理及多媒体消息收发功能的本地化服务。

  • by LukasHaas
  • Go
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 LukasHaas/whatsapp-mcp

使用说明

WhatsApp MCP服务器

这是一把叉子 拉里斯/whatsapp mcp 具有改进的搜索和联系人分辨率。

通过此功能，您可以搜索和阅读您的个人Whatsapp消息（包括图像、视频、文档和音频消息），搜索您的联系人，并向个人或组发送消息。您还可以发送媒体文件，包括图像、视频、文档和音频消息。

它连接到您的 个人WhatsApp帐户 直接通过Whatsapp网络多设备API（使用 怎么回事 图书馆）。您的所有消息都存储在本地SQLite数据库中，只有当代理通过您控制的工具访问它们时，才会发送给LLM（如Claude）。

这里有一个例子，说明当它连接到克劳德时你可以做什么。

注意： 与许多MCP服务器一样，WhatsApp MCP受 致命的三联征这意味着项目注入可能会导致私人数据泄露。

上游变化

完整地址簿搜索

上游MCP仅搜索已同步到本地的联系人 chats 桌子（通常几百个）。这个叉子也搜索 完整的WhatsApp通讯簿 通过whatsmow存储（通常有数千个联系人），这样你就可以找到你最近没有发过消息的人。

LID（链接ID）解析

WhatsApp一直在将一些联系人转换为使用基于LID的JID，而不是基于电话号码的JID。这个分叉使用whatsmow将LID解析为真实的联系人姓名 lid_map 表，因此基于LID的联系人的聊天和消息显示的是正确的名称，而不是不透明的数字ID。

不区分重音和大小写的搜索

搜索“施罗德”现在找到了“施罗德（Schröder）”，“穆尼奥斯（Munoz）”找到了“穆尼奥斯”，等等。所有搜索操作都会对Unicode变音符号进行标准化处理，以便进行比较。

按需聊天同步

新的 /api/sync Go桥上的端点允许请求特定聊天的历史同步。该桥还发送连接状态，以帮助触发WhatsApp的待处理同步数据。

安装

先决条件

  • 走
  • Python 3.6+
  • 拟人克劳德桌面应用程序（或光标）
  • UV（Python包管理器），安装时使用 curl -LsSf https://astral.sh/uv/install.sh | sh
  • FFmpeg(可选的)-仅用于音频消息。如果你想将音频文件作为可播放的WhatsApp语音消息发送，它们必须在 .ogg Opus格式。安装FFmpeg后，MCP服务器将自动转换非Opus音频文件。没有FFmpeg，您仍然可以使用以下命令发送原始音频文件 send_message 随着 media_path.

步骤

  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天后，您可能需要重新进行身份验证。

    提示： 在内部运行网桥（以及可选的MCP服务器） 终端复用器 会话，以便在您关闭终端后它们继续运行：

    tmux new-session -s whatsapp
cd whatsapp-bridge && go run main.go
# Detach with Ctrl-b d — reattach later with: tmux attach -t whatsapp

  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.

通过fly.io（WebSocket代理）远程MCP

如果你想从远程客户端（例如web上的Claude、移动应用程序或服务器端代理）连接到本地MCP，你可以在 fly.io 将MCP流量隧道传输到您的本地计算机。

运作原理

Remote client (Claude / agent)
        │  HTTPS / WSS
        ▼
  fly.io WebSocket proxy  ◄──── persistent outbound WS connection ────  Local machine
                                                                         (tmux session running
                                                                          whatsapp-bridge + MCP server)
  1. 您的本地计算机打开 出站 与fly.io应用程序的WebSocket连接（不需要入站防火墙规则）。
  2. fly.io应用程序通过公共HTTPS/WSS端点将该连接桥接到远程MCP客户端。
  3. MCP消息在两个方向上透明地流动。

设置

  1. 安装fly CLI并登录

    curl -L https://fly.io/install.sh | sh
fly auth login

  2. 创建代理应用程序 --您可以使用任何小型WebSocket中继服务器。一个最小的例子使用 mcp-remote 作为本地侧货运代理：

    # On your local machine, install mcp-remote
npm install -g mcp-remote

# Start the local MCP server with stdio transport (as usual), then expose it:
mcp-remote http://localhost:YOUR_MCP_PORT

    对于fly.io端，创建一个最小的Node/Bun WebSocket中继（请参阅 mcp代理 一个现成的Docker镜像项目）并部署它：

    fly launch --image ghcr.io/sparfenyuk/mcp-proxy:latest --name my-whatsapp-mcp
fly deploy

  3. 指向fly.io上的当地桥梁 --在本地计算机上（最好在tmux会话内）启动隧道：

    # Replace <app-name> with your fly.io app name
mcp-proxy --mode ws-client wss://<app-name>.fly.dev/mcp

    代理将保持与fly.io的持久出站WebSocket连接，以便远程客户端可以随时访问您的本地MCP。

  4. 配置您的远程客户端 --在客户端配置中添加fly.io WebSocket URL作为MCP服务器：

    {
  "mcpServers": {
    "whatsapp": {
      "url": "wss://<app-name>.fly.dev/mcp"
    }
  }
}

注： 在您的tmux会话中保持本地网桥和隧道运行（请参阅上面的tmux提示），以便远程MCP保持可访问。

架构概述

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

  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_消息：使用可选筛选器（日期范围、发件人、聊天、联系人、内容查询）和周围上下文检索邮件。使用 contact_jid 查找涉及某人的任何消息（作为发件人或在他们的直接聊天中）
  • list_chats：列出带有元数据的可用聊天记录
  • get_chat：通过JID、电话号码或联系人获取聊天元数据。提供以下之一 chat_jid （精确查找）， phone_number （通过电话直接聊天），或 contact_jid （所有涉及一个人的聊天）
  • get_message_context：检索特定消息的上下文
  • send_message：发送短信、文件或语音信息。支持 message （文本）， media_path （文件附件），以及 as_audio （转换为Opus语音信息）
  • 下载_媒体：从WhatsApp消息下载媒体并获取本地文件路径

媒体处理功能

MCP服务器支持发送和接收各种媒体类型：

媒体发送

您可以使用统一的 send_message 工具：

  • 图像、视频、文档：使用 send_message 随着 media_path 共享任何支持的媒体类型。
  • 语音信息：使用 send_message 随着 media_path 和 as_audio=True 将音频文件作为可播放的WhatsApp语音消息发送。
    • 为了获得最佳兼容性，音频文件应位于 .ogg Opus格式。
    • 安装FFmpeg后，系统将自动将其他音频格式（MP3、WAV等）转换为所需的格式。
    • 没有FFmpeg，您仍然可以通过以下方式发送原始音频文件 as_audio=False，但它们不会显示为可播放的语音消息。

媒体下载

默认情况下，只有媒体的元数据存储在本地数据库中。该消息将指示媒体已发送。要访问此媒体，您需要使用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)并重新启动网桥以重新进行身份验证。

连接问题

  • Error reading from websocket: websocket: close 1006 (abnormal closure): unexpected EOF：这意味着WhatsApp关闭了底层的web套接字——通常是短暂的网络故障或例行的保活超时。该网桥启用whatsmow的自动重新连接，并在启动时等待稳定的登录会话（最多3分钟），而不是在第一次失败的检查时退出，因此日志中偶尔会出现1006，并自行恢复。如果网桥重复记录错误并且从未到达 ✓ Connected to WhatsApp!，检查WhatsApp服务器的出站流量是否未被防火墙、VPN或代理阻止，以及您的会话是否未从手机中注销（设置>链接设备）。如果会话已删除，请删除 whatsapp-bridge/store/whatsapp.db 并重新启动以重新扫描二维码。

有关其他Claude Desktop集成故障排除，请参阅 MCP文件。该文档包括检查日志和解决常见问题的有用提示。

相关 MCP