Whatsapp MCP Go

MCPAI代理

提供方 iamatulsingh

AI代理 未标注 Token 社区 / 第三方 Claude DesktopClaudeCursor

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

一句话选型结论

按资料字段整理

Whatsapp MCP Go 属于AI代理类 MCP 服务器,传输方式未标注,Token,可直接接入 Claude Desktop、Claude、Cursor,没有现成安装命令,需按官方文档接入。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类AI代理 传输方式未标注 鉴权Token 部署方式未标注
GitHub 星标 9 仓库热度,无公开仓库时显示未标注
工具数 14 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

AI代理
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量14暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

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

安装与配置

未标注 Token
上游未给出传输方式
  1. 1
    准备运行环境

    按官方文档确认运行环境(常见为 Node.js 或 Python),装好后再执行安装命令。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 14 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
给代理接外部能力

让代理在任务中途调用搜索、数据库等真实工具。

多步任务编排

把一串操作拆成步骤,由代理按顺序执行。

自动化重复流程

把固定流程交给代理跑,减少手工操作。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 14 个工具,覆盖面较广,能满足多种调用。
  • 已适配 Claude Desktop、Claude、Cursor,换客户端不用重新研究配置。

先想清楚的地方

  • 没有现成安装命令,需要按官方文档自己填启动命令和参数。
  • 使用前要准备好Token对应的凭据,并按最小权限配置。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在AI代理场景里让模型直接调用外部能力的人。
  • 已经在用 Claude Desktop、Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Whatsapp MCP Go当前 14 未标注 未标注 无 2026-05-17
Filesystem 560c4363 13 未标注 本地部署 无 2026-05-17
Server Everything (everything) 11 stdio · 本地进程 本地部署 有 2026-05-17
Time 7365cb6d 2 SSE · 服务端推送 远程部署 有 2026-05-18
Everything Claude Code 未标注 stdio · 本地进程 本地部署 有 2026-05-17
Openmemory 557e1585 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

AI代理
字段来自项目仓库与公开索引,中文说明由本站标注
提供方iamatulsingh上游标注的维护方 iamatulsingh
分类AI代理本站按上游分类展示
连接方式未标注上游未给出传输方式
鉴权方式Token远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · 未标注本地安装时用到的包标识与运行时
部署类型未标注上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

11.4 KB
来自项目仓库与上游目录的原文,未做删改

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 工具。

步骤

  1. 克隆此存储库```bash
    git clone https://github.com/iamatulsingh/whatsapp-mcp-go.git
    cd whatsapp-mcp-go

1. **运行WhatsApp桥**
导航到whatsapp桥目录并运行Go应用程序:```bash
cd whatsapp-bridge
go run main.go

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

  1. 连接到MCP服务器```bash
    cd whatsapp-mcp-server
    go build -o whatsapp-mcp

将以下json复制为相应的{{PROJECT_BASE_PATH}}值:```json
{
"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编译器。

使其工作的步骤:

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

  2. 启用CGO并运行应用程序``bash 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-mcp`MCP服务器是
始于 **HTTP模式** (端口5777),因为这是唯一的模式
适合长时间运行的容器——请参阅下面的“MCP服务器:stdio与HTTP”
何时使用每个。```bash
# 1. Set the four required vars (in .env at repo root, or in your shell)
cat > .env <` 在每一个 `/api/...` 电话。

### 第一步:获取JWT

```bash
curl -X POST \
-H "Authorization: Bearer $WHATSAPP_API_KEY" \
http://localhost:8080/auth/login
# {"token":"eyJhbGciOiJIUzI1NiIs..."}```

### 第2步:调用API

```bash
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)错误的情况下,

```bash
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客户端版本。

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

或更新所有软件包

```bash
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自动化的开发人员。
```

常见问题

6 问
答案由本站依据条目字段整理,不引用上游原文
Whatsapp MCP Go 怎么安装?

资料没有给出安装命令,请到官方仓库或文档按说明接入;这类条目多数是生态应用,或尚未发布可安装包。

Whatsapp MCP Go 怎么在 Claude Desktop、Claude、Cursor 里配置?

它的传输方式未标注,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Whatsapp MCP Go 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Whatsapp MCP Go 需要 API Key 吗?

资料标注需要Token认证,使用前准备好对应凭据,并按最小权限配置。

Whatsapp MCP Go 支持哪些客户端?

资料标注支持 Claude Desktop、Claude、Cursor;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Whatsapp MCP Go 能提供哪些能力?

资料显示约 14 个工具;能力标签包括 Go、Claude、Docker支持。具体工具清单以官方文档为准。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。