WhatsApp MCP Server

基本能力

产品定位

WhatsApp MCP Server 是一个用于连接和管理个人 WhatsApp 账户的服务，提供消息搜索、发送和管理功能。

核心功能

• 搜索和阅读个人 WhatsApp 消息（包括图片、视频、文档和音频消息）
• 搜索联系人并向个人或群组发送消息
• 发送媒体文件（包括图片、视频、文档和音频消息）
• 本地存储所有消息在 SQLite 数据库中
• 通过 MCP 协议与 LLM（如 Claude）交互

适用场景

• 个人 WhatsApp 消息管理
• 通过 AI 代理（如 Claude）进行 WhatsApp 消息交互
• 批量发送消息或媒体文件

工具列表

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

常见问题解答

• QR 码不显示：尝试重新启动认证脚本，或检查终端是否支持显示 QR 码
• WhatsApp 已登录：如果会话已激活，Go 桥接器将自动重新连接而不显示 QR 码
• 设备限制：WhatsApp 限制链接设备数量，需从手机 WhatsApp 中移除现有设备
• 消息未加载：初始认证后，可能需要几分钟加载消息历史
• WhatsApp 不同步：删除数据库文件并重新启动桥接器以重新认证

使用教程

使用依赖

• Go
• Python 3.6+
• Anthropic Claude Desktop 应用（或 Cursor）
• UV（Python 包管理器），安装命令：curl -LsSf https://astral.sh/uv/install.sh | sh
• FFmpeg（可选）：用于音频消息转换

安装教程

1. 克隆仓库 bash git clone https://github.com/lharries/whatsapp-mcp.git cd whatsapp-mcp
2. 运行 WhatsApp 桥接器 bash cd whatsapp-bridge go run main.go
3. 连接 MCP 服务器 复制提供的 JSON 配置并填写适当的路径
4. 重启 Claude Desktop / Cursor

Windows 兼容性

1. 安装 C 编译器：推荐使用 MSYS2
2. 启用 CGO 并运行应用 bash cd whatsapp-bridge go env -w CGO_ENABLED=1 go run main.go

调试方式

• 确保 Go 应用和 Python 服务器都在运行
• 检查日志以解决常见问题
• 如需重新认证，删除数据库文件并重启桥接器

许可证

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