← 返回目录

WhatsApp MCP

社区

通过 Claude 读取、搜索和发送 WhatsApp 消息

查看安装方法 ↓ 横向对比 GitHub 源仓库 ↗

分类: 其他第 119 / 230
Stars: ★ 248 非常热门
传输方式: stdio（本地进程）
运行环境: Go 1.25+ · Python 3.11+
凭据: 无需凭据
许可证: 其他 / 未声明
最近提交: 29 天前
工具数: 14

54FMRS · D

该服务器功能丰富，支持多种消息操作和媒体处理，但需要注意安全风险和非官方 API 的合规性问题。适合个人或开发环境使用，对于生产环境需要谨慎评估。

最强项 · 文档质量 15/20 最弱项 · 可靠性 7/20

可靠性

7/20

安全与权限

11/20

维护活跃度

11/20

文档质量

15/20

安装易用性

10/20

查看各项评分依据

可靠性 7/20: 清单与README列出的工具大体一致（13个），但README详细记载了send_reaction而服务器清单遗漏该工具，且README架构图声称“14 total”，存在内部矛盾。README宣称有CI、pytest测试、Go lint、Release Please等，但这些只是叙述，所属CI工作流与测试文件无法从提供材料中核实，按静态校准规则，无执行证据时可靠性最高不超过12。此外该服务器由Go桥+Python双组件构成，涉及二维码配对、令牌文件、端口与路径等多个易错环节，README自身也列出大量排障场景，因此仅给7分。
安全与权限 11/20: 证据显示作者有明确的安全设计：桥接API要求bearer token、仅接受回环Host头、媒体路径限制在WHATSAPP_MEDIA_ROOTS、HTTP/SSE默认绑定127.0.0.1、令牌文件owner-only权限、webhook客户端不跟随重定向、安装示例中不含真实令牌。但该服务器的本质是让LLM读取私密消息并可发送消息/文件，README的Security Notice也承认prompt injection可能导致私密数据外泄；send_message/send_file等副作用操作未见任何逐次确认机制。未触发红色警戒线（无恶意代码迹象、无真实凭据泄露），但高度敏感的数据面与缺失确认门禁限制了得分。
维护活跃度 11/20: 仓库未归档，有明确的版本号0.4.1，README提到Release Please、Dependabot、CI、CHANGELOG与贡献者名单，说明存在一定维护活动。但仓库元数据许可证为NOASSERTION，与README声称的MIT不一致；提供材料中也没有提交/发版日期或issue响应情况可供核实，故“持续维护”只能视为未证实的主张。许可证声明不一致与不可验证的治理证据使分数停在11。
文档质量 15/20: README覆盖面很广：前置条件、快速开始、Claude Desktop与Cursor配置JSON、每个工具的参数及自然语言示例、配置表、stdio/http/sse传输说明、故障排查、安全提示、来电记录表结构、架构图与开发命令，并披露了限制（消息/会话上限、历史窗口由手机决定等）。扣分点：send_reaction虽被文档记载却未出现在服务器清单；架构图写14个工具而清单只有13个；LICENSE文件及docs/RELEASING.md、CONTRIBUTING.md的存在无法由提供材料证实。
安装易用性 10/20: README提供了清晰的分步安装说明、可直接粘贴的客户端配置JSON，以及可选的macOS launchd安装脚本。但技术栈较重：需要Go 1.25+、Python 3.11+、uv和手机扫码配对，且必须分别运行Go桥和Python服务器两个组件。清单宣传PyPI包whatsapp-mcp-server，但快速入门从未使用该包，而是克隆仓库并用uv指向本地目录；仅安装PyPI包会缺少Go桥组件。Windows还需MSYS2与CGO。按静态校准，无执行证据时setup最高不超过15，此处为手动多组件流程，故给10。

静态评测 · 未实际运行收录于 2026-08-07

查看 FMRS 评分方法 →

选型与风险

能访问什么读取本地文件写入 / 删除本地文件访问网络连接数据库

适合谁

希望在保留本地消息记录的同时，通过 AI 助手管理 WhatsApp 消息的个人用户
需要以编程方式访问 WhatsApp 聊天数据的开发者

不适合谁

对 WhatsApp 消息安全性要求极高的环境（存在提示注入风险）
需要官方 WhatsApp API 支持的大型企业部署（该服务器使用非官方 Web API）
多用户或需要细粒度访问控制的环境（当前实现是单一用户）

所需权限

读取和写入 WhatsApp 消息（通过桥接器）
读取和写入本地 SQLite 数据库中的消息历史
发送和接收媒体文件
访问本地文件系统（用于媒体文件路径）
监听本地 REST API 端口（默认 8080）

风险与副作用

提示注入：恶意消息可能诱使 AI 执行意外操作，导致数据泄露
非官方 API：使用逆向工程的 WhatsApp Web API，可能违反 WhatsApp 服务条款
敏感数据暴露：消息存储在本地，但 AI 可能会将内容发送到外部服务
无身份验证：MCP 服务器本身没有认证，暴露在网络时容易被滥用

安装接入

准备工作

运行环境：Go 1.25+ · Python 3.11+

WHATSAPP_BRIDGE_TOKEN 可选密钥 bridge REST 调用的 Bearer 令牌，首次启动 bridge 时生成并写入 .bridge-token 文件。

其他可选配置项（10 个）

WHATSAPP_BRIDGE_PORT 可选 Go bridge REST API 端口，默认 8080。

WEBHOOK_URL 可选接收转发消息的 webhook 地址，默认 http://localhost:8769/whatsapp/webhook。

FORWARD_SELF 可选是否转发自己发送的消息，默认 true。

WHATSAPP_DB_PATH 可选本地 SQLite 消息库路径，默认 ../whatsapp-bridge/store/messages.db。

WHATSMEOW_DB_PATH 可选 whatsmeow 会话库路径（用于 LID↔手机号解析），默认 ../whatsapp-bridge/store/whatsapp.db。

WHATSAPP_API_URL 可选 Go bridge REST API 地址，默认 http://localhost:8080/api。

WHATSAPP_MEDIA_ROOTS 可选允许发送媒体的目录白名单，默认 ~/.local/share/whatsapp-mcp/outbox。

WHATSAPP_MCP_TRANSPORT 可选 MCP 传输方式：stdio、http 或 sse，默认 stdio。

WHATSAPP_MCP_HOST 可选 http/sse 传输的绑定地址，默认 127.0.0.1。

WHATSAPP_MCP_PORT 可选 http/sse 传输的端口，默认 8000。

克隆仓库并进入目录。
启动 Go 桥接器：cd whatsapp-bridge && go run .，首次启动时扫描二维码进行认证。
将 MCP 服务器配置添加到 Claude Desktop 的配置文件（claude_desktop_config.json）或 Cursor 的配置（~/.cursor/mcp.json）中，使用 uv 命令并指定 whatstapp-mcp-server 目录。
重启 Claude Desktop 或 Cursor。

claude_desktop_config.json

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

以 Claude Desktop 为例。其他客户端的配置文件位置或字段可能不同（如 VS Code 使用 servers 字段），可用下方配置生成器转换。

.vscode/mcp.json

{
  "servers": {
    "whatsapp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/whatsapp-mcp/whatsapp-mcp-server",
        "run",
        "main.py"
      ]
    }
  }
}

写入项目的 .vscode/mcp.json（VS Code 使用 servers 字段）。

Terminal

claude mcp add whatsapp -- uv --directory /path/to/whatsapp-mcp/whatsapp-mcp-server run main.py

在终端运行；先把 <…> 占位符换成你自己的值。

生成并校验客户端配置

验证是否装好

启动 Go bridge（cd whatsapp-bridge && go run .）并扫码后，重启 Claude Desktop，工具列表中应出现 search_contacts 和 list_messages 等工具；用“列出我的聊天”提问即可验证连接。

常见排障

二维码不显示：重启桥接器，检查终端二维码支持
设备数量达到限制：在 WhatsApp 设置中移除已关联设备
消息不加载：初始同步可能需要几分钟，确保桥接器正常运行
桥接器返回 401 未授权：重启桥接器以生成 .bridge-token，然后重启 MCP 服务器
桥接器返回 403 主机禁止：确保 WHATSAPP_API_URL 使用 127.0.0.1 或 localhost
媒体文件路径被拒绝：将文件移动到默认 outbox 或配置 WHATSAPP_MEDIA_ROOTS

试试这样问

连接成功后，可以直接对 AI 助手这样说：

搜索名字里有 John 的联系人
显示今天的最近 100 条消息
给 +1234567890 发送“你好！”
给家庭群聊里最后一条消息点个赞

工具能力 14

search_contacts 只读

按名称或电话号码搜索联系人

get_contact 只读

将电话号码解析为联系人姓名

list_messages 只读

获取带有过滤器、日期范围和排序的消息

list_chats 只读

列出所有带有元数据的聊天

get_chat 只读

按 JID 获取特定聊天的元数据

get_direct_chat_by_contact 只读

查找与联系人的直接消息聊天

get_contact_chats 只读

列出涉及联系人的所有聊天

get_last_interaction 只读

获取与联系人的最后一条消息

展开其余 6 个工具

get_message_context 只读

获取特定消息周围的消息

send_message 写入

向联系人或群组发送文本消息

send_reaction 写入

向消息发送（或移除）表情符号反应

send_file 写入

发送媒体文件（图片、视频、文档）

send_audio_message 写入

发送语音消息（自动转换为 Opus 格式）

download_media 写入

从收到的消息中下载媒体

使用场景

让 Claude 通过 WhatsApp 发送消息给联系人

查询聊天历史并检索特定对话

自动下载收到的媒体文件

将 WhatsApp 消息集成到 AI 工作流中

支持客户端

Claude Desktop

Cursor

依据项目文档列出，未经本站实测。

详细介绍

这是一个 Model Context Protocol (MCP) 服务器，用于将 Claude 连接到 WhatsApp，实现消息的读取、搜索和发送。它包含一个 Python MCP 服务器和一个 Go 桥接器，通过 WhatsApp Web API 与 WhatsApp 交互，并将消息本地存储在 SQLite 数据库中。该服务器提供联系人搜索、消息列表、聊天管理、媒体发送与下载等工具，并支持通过 Webhook 转发入站消息。