WhatsApp MCP Server

基本能力

产品定位

WhatsApp MCP Server 是一个基于 Model Context Protocol (MCP) 的 WhatsApp 服务端，允许用户通过 AI 代理（如 Claude）管理和交互 WhatsApp 消息。

核心功能

1. 消息管理：搜索和读取个人 WhatsApp 消息（包括图片、视频、文档和音频消息）。
2. 联系人管理：搜索联系人并向个人或群组发送消息。
3. 媒体文件支持：支持发送图片、视频、文档和音频消息。
4. 本地存储：所有消息存储在本地 SQLite 数据库中，仅当 AI 代理通过工具访问时才发送到 LLM。
5. 多设备支持：通过 WhatsApp 网页多设备 API 连接个人 WhatsApp 账户。

适用场景

1. 通过 AI 代理（如 Claude）管理和交互 WhatsApp 消息。
2. 自动化发送消息和媒体文件。
3. 搜索和检索历史消息。

工具列表

1. search_contacts：按名称或电话号码搜索联系人。
2. list_messages：检索带有可选过滤器和上下文的消息。
3. list_chats：列出可用的聊天及其元数据。
4. get_chat：获取特定聊天的信息。
5. get_direct_chat_by_contact：查找与特定联系人的直接聊天。
6. get_contact_chats：列出涉及特定联系人的所有聊天。
7. get_last_interaction：获取与联系人的最新消息。
8. get_message_context：检索特定消息的上下文。
9. send_message：向指定的电话号码或群组 JID 发送 WhatsApp 消息。
10. send_file：向指定的收件人发送文件（图片、视频、原始音频、文档）。
11. send_audio_message：将音频文件作为 WhatsApp 语音消息发送（需要文件为 .ogg opus 格式或安装 ffmpeg）。
12. download_media：从 WhatsApp 消息下载媒体并获取本地文件路径。

常见问题解答

1. QR 码不显示：尝试重新启动身份验证脚本。如果问题仍然存在，检查终端是否支持显示 QR 码。
2. WhatsApp 已登录：如果会话已激活，Go 桥将自动重新连接而不显示 QR 码。
3. 设备限制：WhatsApp 限制了链接设备的数量。如果达到限制，需要从手机 WhatsApp 中删除现有设备（设置 > 链接设备）。
4. 消息未加载：初始身份验证后，可能需要几分钟才能加载消息历史记录，尤其是聊天较多时。
5. WhatsApp 不同步：如果 WhatsApp 消息与桥不同步，删除数据库文件（whatsapp-bridge/store/messages.db 和 whatsapp-bridge/store/whatsapp.db）并重新启动桥以重新进行身份验证。

使用教程

使用依赖

1. Go
2. Python 3.6+
3. Anthropic Claude Desktop 应用（或 Cursor）
4. UV（Python 包管理器），安装命令： bash curl -LsSf https://astral.sh/uv/install.sh | sh
5. FFmpeg（可选） - 仅用于音频消息。如果要将音频文件作为可播放的 WhatsApp 语音消息发送，它们必须是 .ogg Opus 格式。安装 FFmpeg 后，MCP 服务器将自动转换非 Opus 音频文件。如果没有 FFmpeg，仍然可以使用 send_file 工具发送原始音频文件。

安装教程

1. 克隆仓库 bash git clone https://github.com/lharries/whatsapp-mcp.git cd whatsapp-mcp
2. 运行 WhatsApp 桥 bash cd whatsapp-bridge go run main.go 首次运行时，会提示扫描 QR 码。使用 WhatsApp 手机应用扫描 QR 码进行身份验证。
3. 连接到 MCP 服务器 复制以下 JSON 并替换适当的 {{PATH}} 值： json { "mcpServers": { "whatsapp": { "command": "{{PATH_TO_UV}}", // 运行 `which uv` 并将输出放在这里 "args": [ "--directory", "{{PATH_TO_SRC}}/whatsapp-mcp/whatsapp-mcp-server", // 进入仓库，运行 `pwd` 并输入输出 + "/whatsapp-mcp-server" "run", "main.py" ] } } } 对于 Claude，将此保存为 claude_desktop_config.json 在 Claude Desktop 配置目录中： ~/Library/Application Support/Claude/claude_desktop_config.json 对于 Cursor，将此保存为 mcp.json 在 Cursor 配置目录中： ~/.cursor/mcp.json
4. 重启 Claude Desktop / Cursor 打开 Claude Desktop，现在应该可以看到 WhatsApp 作为可用集成。或重启 Cursor。

Windows 兼容性

1. 安装 C 编译器 推荐使用 MSYS2 为 Windows 安装 C 编译器。安装 MSYS2 后，确保将 ucrt64\bin 文件夹添加到 PATH 中。
2. 启用 CGO 并运行应用 bash cd whatsapp-bridge go env -w CGO_ENABLED=1 go run main.go

调试方式

1. 确保 Go 应用程序和 Python 服务器都在运行以使集成正常工作。
2. 如果遇到权限问题，尝试将 UV 添加到 PATH 或使用可执行文件的完整路径。

许可证

该项目遵循 MIT 开源许可条款，请参阅 MIT 了解完整条款。