WhatsApp MCP 服务器是一个基于模型上下文协议（MCP）的服务器，用于将个人 WhatsApp 账户与 AI 代理（如 Claude）连接。通过该服务器，AI 可以搜索和读取个人 WhatsApp 消息（包括图片、视频、文档和音频消息），搜索联系人，并向个人或群组发送消息，还可发送媒体文件。它直接通过 WhatsApp Web 多设备 API（使用 whatsmeow 库）连接到个人 WhatsApp 账户。所有消息本地存储在 SQLite 数据库中，仅在代理通过工具访问时才会发送给 LLM（如 Claude）。
用途：为 AI 助手提供访问和操作 WhatsApp 个人账户的能力，实现消息查询、联系人管理和消息发送。
主要能力：
- 搜索联系人（按姓名或电话号码）。
- 检索消息（支持过滤和上下文）。
- 列出聊天、获取聊天信息、按联系人查找直接聊天、列出涉及某联系人的所有聊天、获取最近互动、获取消息上下文。
- 发送消息到指定电话号码或群组 JID。
- 发送文件（图片、视频、原始音频、文档）。
- 发送音频消息作为 WhatsApp 语音消息（需 .ogg Opus 格式或安装 FFmpeg 自动转换）。
- 下载消息中的媒体文件并获取本地路径。
- 支持接收各种媒体类型，默认仅存储元数据，需使用 download_media 工具下载媒体。
使用方式：
- 前置条件：Anthropic Claude Desktop 应用（或 Cursor）、UV（Python 包管理器，安装命令：curl -LsSf https://astral.sh/uv/install.sh | sh）、FFmpeg（可选，仅音频消息需要）。
- 克隆仓库：git clone https://github.com/lharries/whatsapp-mcp.git 然后 cd whatsapp-mcp。
- 运行 WhatsApp 桥接：进入 whatsapp-bridge 目录运行 Go 应用：cd whatsapp-bridge 然后 go run main.go。首次运行会提示扫描二维码，用 WhatsApp 手机应用扫描以认证。约 20 天后可能需要重新认证。
- 连接 MCP 服务器：复制提供的 JSON 配置，替换 {{PATH}} 值。对于 Claude，保存为 claude_desktop_config.json 到 ~/Library/Application Support/Claude/claude_desktop_config.json；对于 Cursor，保存为 mcp.json 到 ~/.cursor/mcp.json。
- 重启 Claude Desktop 或 Cursor，即可看到 WhatsApp 集成。
Windows 兼容性：go-sqlite3 需要启用 CGO 并安装 C 编译器。推荐使用 MSYS2 安装 C 编译器，并将 ucrt64\bin 添加到 PATH。然后启用 CGO 并运行：cd whatsapp-bridge，go env -w CGO_ENABLED=1，go run main.go。否则可能遇到错误：Binary was compiled with 'CGO_ENABLED=0', go-sqlite3 requires cgo to work。
架构概述：
- Go WhatsApp 桥接（whatsapp-bridge/）：连接 WhatsApp Web API，处理二维码认证，将消息历史存储在 SQLite。
- Python MCP 服务器（whatsapp-mcp-server/）：实现 MCP，提供标准化工具供 Claude 交互。 消息历史存储在 whatsapp-bridge/store/ 下的 SQLite 数据库中，包含聊天和消息表，消息已索引以便高效搜索。
可用工具：search_contacts、list_messages、list_chats、get_chat、get_direct_chat_by_contact、get_contact_chats、get_last_interaction、get_message_context、send_message、send_file、send_audio_message、download_media。
媒体处理：可发送图片、视频、文档（send_file），语音消息（send_audio_message，建议 .ogg Opus 格式，安装 FFmpeg 可自动转换其他格式）。默认仅存储媒体元数据，需用 download_media 下载并获取本地路径。
技术细节：Claude 发送请求到 Python MCP 服务器，MCP 服务器查询 Go 桥接或直接查询 SQLite，Go 访问 WhatsApp API 并保持数据库更新。发送消息时请求流经 MCP 服务器、Go 桥接到 WhatsApp。
故障排除：
- uv 权限问题：添加到 PATH 或使用完整路径。
- 确保 Go 应用和 Python 服务器都在运行。
- 二维码不显示：重启认证脚本，检查终端是否支持显示二维码。
- 已登录：Go 桥接自动重连，不显示二维码。
- 设备限制：需在手机 WhatsApp 中移除已有设备（设置 > 关联设备）。
- 消息未加载：初始认证后可能需要几分钟加载历史。
- 不同步：删除 whatsapp-bridge/store/messages.db 和 whatsapp-bridge/store/whatsapp.db，重启桥接重新认证。
限制与注意：
- 如许多 MCP 服务器一样，WhatsApp MCP 受“致命三要素”影响，项目注入可能导致私人数据泄露。
- 所有消息本地存储，仅在代理通过工具访问时发送给 LLM。
- 音频消息需 .ogg Opus 格式或安装 FFmpeg 转换。
- Windows 需额外配置 CGO 和 C 编译器。
- 约 20 天后可能需要重新认证。
- WhatsApp 有链接设备数量限制。
