快速接入

先看主来源和安装命令，再打开仓库或文档；下面只保留这个条目的关键接入事实。

详细介绍

WhatsApp‑MCP（Go版）

一个轻量级的WhatsApp MCP服务器和网桥——完全用Go重写，以实现简单性、可移植性和现实世界的自动化工作流程。

这个项目是对原作的重新想象 whatsapp mcp 通过 拉里斯，他使用Python MCP服务器和Go WhatsApp客户端创建了第一个WhatsApp MCP桥，由 WhatsMeow他们的工作展示了Claude Desktop如何通过MCP协议与WhatsApp进行交互，如果没有这个基础，这个项目就不会存在。

开始 whatsapp-bridge ->然后跑 whatsapp-mcp-server 在您偏好的模式下（STDIO或HTTP）。

安装

先决条件

去
拟人克劳德桌面应用程序（或光标）或 n8n 工作流程
FFmpeg(_可选的_)-仅用于音频消息。如果你想将音频文件作为可播放的WhatsApp语音消息发送，它们必须在 .ogg Opus格式。安装FFmpeg后，MCP服务器将自动转换非Opus音频文件。没有FFmpeg，您仍然可以使用 send_file 工具。

步骤

克隆此存储库

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

运行WhatsApp桥

导航到whatsapp桥目录并运行Go应用程序：

   cd whatsapp-bridge
   go run main.go

第一次运行它时，系统会提示您扫描二维码。使用WhatsApp移动应用程序扫描二维码进行身份验证。大约20天后，您可能需要重新进行身份验证。

3. 连接到MCP服务器

      cd whatsapp-mcp-server
      go build -o whatsapp-mcp

将以下json复制为相应的{{PROJECT_BASE_PATH}}值：

      {
           "mcpServers": {
               "whatsapp-mcp": {
                  "command": "{{PROJECT_BASE_PATH}}/whatsapp-mcp-server/whatsapp-mcp",
                  "env": {
                       "WHATSAPP_API_KEY": "c3VwZXItbG9uZy1yYW5kb20tc3RyaW5nLW1pbmltdW0tb2YtNjQtY2hhcmFjdGVycy15b3UtbmVlZC10by1wYXN0ZS1oZXJl"
                  }
               }
           },
           "preferences": {
               "sidebarMode": "chat",
               "coworkScheduledTasksEnabled": false
           }
       }

对于 克劳德，将此另存为 claude_desktop_config.json 在您的Claude Desktop配置目录中：

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

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

      ~/.cursor/mcp.json

Windows兼容性

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

使其工作的步骤：

安装C编译器\

我们建议使用 Msys 2 安装适用于Windows的C编译器。安装MSYS2后，请确保添加 ucrt64\bin 文件夹到您的 PATH.\ → 提供分步指南这里.

启用CGO并运行应用程序

   cd whatsapp-bridge
   go env -w CGO_ENABLED=1
   go run main.go # or use this to enabled webhook and http streaming, `WEBHOOK_URL=http://192.168.178.119:5777/sse IS_HTTP=true go run main.go`

或者在Docker中运行所有内容

该回购交易 docker-compose.yaml 根上生出三个服务： postgres, wa-bridge，以及 wa-mcpMCP服务器是始于 HTTP模式 （端口5777），因为这是唯一的模式适合长时间运行的容器——请参阅下面的“MCP服务器：stdio与HTTP” 何时使用每个。

# 1. Set the four required vars (in .env at repo root, or in your shell)
cat > .env ` 在每一个 `/api/...` 电话。

### 第一步：获取JWT

curl -X POST \ -H "Authorization: Bearer $WHATSAPP_API_KEY" \ http://localhost:8080/auth/login

{"token":"eyJhbGciOiJIUzI1NiIs..."}


### 第2步：调用API

TOKEN=eyJhbGciOiJIUzI1NiIs... curl -H "Authorization: Bearer $TOKEN" http://localhost:8080/api/chats


MCP服务器自动执行以下操作：配置 `WHATSAPP_API_KEY` 而它
根据需要获取/刷新JWT。

### 速率限制

`/auth/login` 是每个客户端IP的速率限制（默认值：5次尝试/分钟）。
覆盖 `AUTH_LOGIN_RATE=/` （例如。 `10/30s`).a后面
反向代理，终止上游速率限制——网桥当前使用
`r.RemoteAddr` 不咨询 `X-Forwarded-For`.

## 架构概述

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

1. **WhatsApp桥** (`whatsapp-bridge/`)：Go应用程序，连接到WhatsApp的web API，通过二维码处理身份验证，并将消息历史存储在SQLite中。它是WhatsApp和MCP服务器之间的桥梁。

1. **MCP服务器** (`whatsapp-mcp-server/`)模型上下文协议（MCP）的Go实现，为Claude提供了与WhatsApp数据交互和发送/接收消息的标准化工具。

### 数据存储

- 所有消息历史记录都存储在 `postgres` 默认情况下，您需要创建一个数据库名称 `whatsapp` 或者在 `whatsapp-bridge/store/` 目录
- 数据库维护聊天和消息表
- 邮件被编入索引，以便高效搜索和检索

### 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消息下载媒体并获取本地文件路径
- **get_login_status**：检查网桥是否已连接并登录到WhatsApp。退货 `{connected, logged_in, pairing_required}`.
- **get_pairing_qr**：将WhatsApp配对QR提取为PNG图像。当需要配对时返回图像内容，或者当网桥已登录时返回文本消息。可用于从MCP感知UI内部而不是从终端完成初始设备链接流。

### 媒体处理功能

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向MCP服务器发送请求
1. MCP服务器向Go桥查询WhatsApp数据或直接查询SQLite数据库
1. Bridge访问WhatsApp API，并使SQLite或Postgres数据库保持最新
1. 数据通过链流回克劳德
1. 发送消息时，请求从Claude通过MCP服务器流向网桥和WhatsApp

## 故障排除

- 确保Bridge应用程序和MCP服务器都在运行，以便集成正常工作。

- 在Bridge Go服务器中出现客户端过时（405）错误的情况下，

06:13:28.434 [Client INFO] Starting WhatsApp client... 2025/07/29 06:13:28 Connecting to postgres 06:13:30.402 [Client ERROR] Client outdated (405) connect failure (client version: 2.3000.1021018791) 06:13:30.403 [Client/Socket ERROR] Error reading from websocket: websocket: close 1006 (abnormal closure): unexpecte 06:13:30.675 [Client ERROR] Failed to establish stable connection


  运行以下命令并修复升级后代码中的任何错误，桥接代码将自动更新whatsapp客户端版本。

go get -u go.mau.fi/whatsmeow@latest


  或更新所有软件包

go get -u


### 身份验证问题

- **二维码未显示**：如果二维码没有出现，请尝试重新启动身份验证脚本。如果问题仍然存在，请检查您的终端是否支持显示二维码。
- **WhatsApp已登录**：如果您的会话已处于活动状态，Go桥将自动重新连接，而不会显示二维码。
- **已达到设备限制**WhatsApp限制了链接设备的数量。如果达到此限制，您需要从手机上的WhatsApp中删除现有设备（设置>链接设备）。
- **未加载邮件**：初始身份验证后，可能需要几分钟才能加载您的消息历史记录，特别是如果您有很多聊天记录。
- **WhatsApp不同步**：如果您的WhatsApp消息与网桥不同步，请删除这两个数据库文件(`whatsapp-bridge/store/messages.db` 和 `whatsapp-bridge/store/whatsapp.db`)并重新启动网桥以重新进行身份验证。

这个分叉采用了核心思想，并用不同的哲学对其进行了重建：\
**一种语言、一种二进制、干净的架构和灵活的部署。**

______________________________________________________________________

## 为什么这个项目存在

最初的项目很棒，但它是专门为 **克劳德桌面版**，它的架构有一些限制，这使得扩展或部署它变得更加困难。这个叉子是为了解决这些痛点而创建的。

- \***单一语言：Go中的一切**
  最初的设计将责任分开：这大大简化了开发和分发。

- **干净的体系结构：没有混合数据库逻辑**
  将所有数据库逻辑移入网桥

- **SQLite还是PostgreSQL——你的选择**
  原始项目仅支持SQLite。

- **两种通信模式：STDIO+HTTP** 最初的项目仅为Claude Desktop（STDIO MCP）构建。这使得该项目的可用性远远超出了Claude Desktop。

- **Docker支持** 这使得部署变得轻而易举：

* 服务器
* 容器
* 编排器
* 本地开发

______________________________________________________________________

## 特性

- 完整的WhatsApp客户端使用 **WhatsMeow**
- Pure Go MCP服务器
- 清洁MCP和桥梁之间的API边界
- SQLite或PostgreSQL支持
- STDIO+HTTP模式
- 轻量级Docker镜像
- 使用Docker Compose轻松部署
- 没有Python依赖项
- 无混合数据库逻辑
- 生产就绪架构

______________________________________________________________________

## 学分

该项目由两位主要贡献者承担：

### **原作者：lharries**

WhatsApp‑MCP的最初想法、架构和实现来自\
**https://github.com/lharries/whatsapp-mcp**

他们的工作展示了如何使用MCP来桥接WhatsApp和Claude Desktop。\
如果没有他们的项目，这个分叉就不会存在。

### **WhatsMeow**

WhatsApp客户端功能由令人难以置信的Go库提供支持：\
**https://github.com/tulir/whatsmeow**

没有WhatsMeow，这一切都是不可能的。

______________________________________________________________________

## 为什么你可以使用这个叉子

如果需要，请选择此版本：

- 更干净的建筑
- 单语言代码库
- 便携式二进制文件
- Docker支持
- PostgreSQL支持
- 自动化工作流的HTTP支持
- 一个更易于维护和扩展的项目

目标不是取代原始项目，而是提供一种满足不同需求的替代方案，特别是对于喜欢Go或希望在生产环境中部署基于MCP的WhatsApp自动化的开发人员。

目录标签

GoClaudeDocker支持WhatsApp自动化本地部署Go语言开发消息桥接MCP协议

支持客户端

Claude DesktopClaudeCursor

接入字段

传输方式（transport，传输协议）

未说明

鉴权方式（authType，认证方式）

token

工具数量（toolCount，工具数）

14

资源数量（resourceCount，资源数）

0

提示词数量（promptCount，提示词数）

0

权限和风险

未说明token部署方式未说明

接入前请确认传输方式、认证方式和部署位置，并根据实际工具能力限制访问范围。

安装前确认

不要直接授予不必要的文件、网络或账号权限；先核对安装命令和配置内容。

仍需确认：installCommand

来源信息

MCP World

mcpworld.com

/detail/4545f67d56fff26fada0198389ba98d3

一个轻量级的WhatsApp MCP服务器和桥接工具，用Go语言重写，用于实现WhatsApp自动化工作流程。

继续浏览同类 MCP

更多AI代理 MCP（18,706）返回 MCP 目录

上一个 MCP

Whatsapp MCP F1c2957b

一个提供WhatsApp消息发送、读取和搜索功能的集成工具，支持MCP服务器和CLI工具两种使用方式。

下一个 MCP

Whatsapp MCP Server 384748ba

OWL x WhatsApp MCP Server是一个集成WhatsApp消息服务与多代理框架的应用，通过Streamlit界面实现AI代理与WhatsApp数据的交互，支持消息搜索、发送和实时信息检索。

Whatsapp MCP Go