适合谁
- 希望在保留本地消息记录的同时，通过 AI 助手管理 WhatsApp 消息的个人用户
- 需要以编程方式访问 WhatsApp 聊天数据的开发者
W
54FMRS · D
该服务器功能丰富，支持多种消息操作和媒体处理，但需要注意安全风险和非官方 API 的合规性问题。适合个人或开发环境使用，对于生产环境需要谨慎评估。
这是一个 Model Context Protocol (MCP) 服务器，用于将 Claude 连接到 WhatsApp，实现消息的读取、搜索和发送。它包含一个 Python MCP 服务器和一个 Go 桥接器，通过 WhatsApp Web API 与 WhatsApp 交互，并将消息本地存储在 SQLite 数据库中。该服务器提供联系人搜索、消息列表、聊天管理、媒体发送与下载等工具，并支持通过 Webhook 转发入站消息。
工具能力
search_contacts
按名称或电话号码搜索联系人
get_contact
将电话号码解析为联系人姓名
list_messages
获取带有过滤器、日期范围和排序的消息
list_chats
列出所有带有元数据的聊天
get_chat
按 JID 获取特定聊天的元数据
get_direct_chat_by_contact
查找与联系人的直接消息聊天
get_contact_chats
列出涉及联系人的所有聊天
get_last_interaction
获取与联系人的最后一条消息
get_message_context
获取特定消息周围的消息
send_message
向联系人或群组发送文本消息
send_reaction
向消息发送（或移除）表情符号反应
send_file
发送媒体文件（图片、视频、文档）
send_audio_message
发送语音消息（自动转换为 Opus 格式）
download_media
从收到的消息中下载媒体
安装接入
- 克隆仓库并进入目录。2. 启动 Go 桥接器：
cd whatsapp-bridge && go run .，首次启动时扫描二维码进行认证。3. 将 MCP 服务器配置添加到 Claude Desktop 的配置文件（claude_desktop_config.json）或 Cursor 的配置（~/.cursor/mcp.json）中，使用 uv 命令并指定 whatstapp-mcp-server 目录。4. 重启 Claude Desktop 或 Cursor。
claude_desktop_config.json
{
"mcpServers": {
"whatsapp": {
"command": "uv",
"args": [
"--directory",
"/path/to/whatsapp-mcp/whatsapp-mcp-server",
"run",
"main.py"
]
}
}
}
选型与风险
不适合谁
- 对 WhatsApp 消息安全性要求极高的环境（存在提示注入风险）
- 需要官方 WhatsApp API 支持的大型企业部署（该服务器使用非官方 Web API）
- 多用户或需要细粒度访问控制的环境（当前实现是单一用户）
所需权限
- 读取和写入 WhatsApp 消息（通过桥接器）
- 读取和写入本地 SQLite 数据库中的消息历史
- 发送和接收媒体文件
- 访问本地文件系统（用于媒体文件路径）
- 监听本地 REST API 端口（默认 8080）
风险与副作用
- 提示注入：恶意消息可能诱使 AI 执行意外操作，导致数据泄露
- 非官方 API：使用逆向工程的 WhatsApp Web API，可能违反 WhatsApp 服务条款
- 敏感数据暴露：消息存储在本地，但 AI 可能会将内容发送到外部服务
- 无身份验证：MCP 服务器本身没有认证，暴露在网络时容易被滥用
常见排障
- 二维码不显示：重启桥接器，检查终端二维码支持
- 设备数量达到限制：在 WhatsApp 设置中移除已关联设备
- 消息不加载：初始同步可能需要几分钟，确保桥接器正常运行
- 桥接器返回 401 未授权：重启桥接器以生成 .bridge-token，然后重启 MCP 服务器
- 桥接器返回 403 主机禁止：确保 WHATSAPP_API_URL 使用 127.0.0.1 或 localhost
- 媒体文件路径被拒绝：将文件移动到默认 outbox 或配置 WHATSAPP_MEDIA_ROOTS
使用场景
让 Claude 通过 WhatsApp 发送消息给联系人
查询聊天历史并检索特定对话
自动下载收到的媒体文件
将 WhatsApp 消息集成到 AI 工作流中
支持客户端
Claude Desktop完整支持
Cursor完整支持