内容
# WhatsApp MCP 服务器
这是一个用于 WhatsApp 的模型上下文协议（MCP）服务器。
使用它，您可以搜索和阅读您的个人 WhatsApp 消息（包括图片、视频、文档和语音消息），搜索您的联系人，并向个人或群组发送消息。您还可以发送包括图片、视频、文档和语音消息在内的媒体文件。
它通过 WhatsApp 网页多设备 API（使用 [whatsmeow](https://github.com/tulir/whatsmeow) 库）直接连接到您的**个人 WhatsApp 账户**。您的所有消息都存储在本地 SQLite 数据库中，只有在代理通过工具访问它们时才会发送到 LLM（如 Claude）。
以下是连接 Claude 时可以执行的操作示例。
> *注意:* 与许多 MCP 服务器一样，WhatsApp MCP 受制于[致命三要素](https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/)。这意味着项目注入可能导致私人数据泄露。
## 安装
### 先决条件
- Go
- Python 3.6+
- Anthropic Claude 桌面应用程序（或 Cursor）
- UV（Python 包管理器），使用 `curl -LsSf https://astral.sh/uv/install.sh | sh` 安装
- 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 桥接**
导航到 whatsapp-bridge 目录并运行 Go 应用程序：
```bash
cd whatsapp-bridge
go run main.go
```
首次运行时，您将被提示扫描二维码。使用 WhatsApp 移动应用程序扫描二维码以进行身份验证。
大约 20 天后，您可能需要重新身份验证。
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 桌面配置目录中：
```
~/Library/Application Support/Claude/claude_desktop_config.json
```
对于 **Cursor**，将此保存为 `mcp.json`，位于您的 Cursor 配置目录中：
```
~/.cursor/mcp.json
```
4. **重启 Claude Desktop / Cursor**
打开 Claude Desktop，您现在应该看到 WhatsApp 作为一个可用的集成。
或重启 Cursor。
### Windows 兼容性
在 Windows 上运行此项目需要一些额外的设置（启用 CGO、安装 C 编译器等）。请参阅此仓库中的完整逐步指南：**[WINDOWS-SETUP-GUIDE.pdf](WINDOWS-SETUP-GUIDE.pdf)**。
## 架构概述
该应用程序由两个主要组件组成：
1. **Go WhatsApp 桥接**（`whatsapp-bridge/`）：一个 Go 应用程序，连接到 WhatsApp 的网页 API，处理通过二维码的身份验证，并将消息历史记录存储在 SQLite 中。它作为 WhatsApp 和 MCP 服务器之间的桥梁。
2. **Python MCP 服务器**（`whatsapp-mcp-server/`）：一个 Python 服务器，实现模型上下文协议（MCP），为 Claude 提供与 WhatsApp 数据交互和发送/接收消息的标准化工具。
### 数据存储
- 所有消息历史记录存储在 `whatsapp-bridge/store/` 目录中的 SQLite 数据库中
- 数据库维护聊天和消息表格
- 消息索引用于高效搜索和检索
## 用法
连接后，您可以通过 Claude 与 WhatsApp 联系人交互，利用 Claude 的 AI 功能在 WhatsApp 对话中。
### MCP 工具
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 消息中下载媒体并获取本地文件路径
- **mark_chat_as_unread**：将聊天标记为未读，以便显示未读指示器（在向聊天发送消息给自己时很有用，因为 WhatsApp 否则会将其视为已读）。同步到您的手机和所有链接设备。
- **mark_chat_as_read**：将聊天标记为已读，清除未读指示
### 媒体处理功能
MCP 服务器支持发送和接收各种媒体类型：
#### 媒体发送
您可以向 WhatsApp 联系人发送各种媒体类型：
- **图片、视频、文档**：使用 `send_file` 工具分享任何支持的媒体类型。
- **语音消息**：使用 `send_audio_message` 工具发送音频文件作为可播放的 WhatsApp 语音消息。
- 为最佳兼容性，音频文件应为 `.ogg` Opus 格式。
- 安装 FFmpeg 后，系统将自动将其他音频格式（MP3、WAV 等）转换为所需格式。
- 没有 FFmpeg，您仍然可以使用 `send_file` 工具发送原始音频文件，但它们不会显示为可播放的语音消息。
#### 媒体下载
默认情况下，本地数据库仅存储媒体的元数据。消息将指示媒体已发送。要访问此媒体，您需要使用 `download_media` 工具，该工具获取 `message_id` 和 `chat_jid`（在打印包含媒体的消息时显示），下载媒体，然后返回文件路径，可以打开或传递给另一个工具。
## 技术细节
1. Claude 向 Python MCP 服务器发送请求
2. MCP 服务器查询 Go 桥接以获取 WhatsApp 数据或直接查询 SQLite 数据库
3. Go 访问 WhatsApp API 并保持 SQLite 数据库更新
4. 数据通过链条流回 Claude
5. 发送消息时，请求从 Claude 流经 MCP 服务器到 Go 桥接，然后到 WhatsApp
## 故障排除
- 如果您在运行 uv 时遇到权限问题，您可能需要将其添加到 PATH 或使用可执行文件的完整路径。
- 确保 Go 应用程序和 Python 服务器都运行，集成才能正常工作。
### 身份验证问题
- **二维码不显示**：如果二维码不出现，请尝试重新启动身份验证脚本。如果问题仍然存在，请检查您的终端是否支持显示二维码。
- **WhatsApp 已登录**：如果您的会话已经激活，Go 桥接将自动重新连接，而不会显示二维码。
- **达到设备限制**：WhatsApp 限制了链接设备的数量。如果您达到此限制，则需要从手机上的 WhatsApp （设置 > 链接设备）中删除现有设备。
- **无消息加载**：初始身份验证后，可能需要几分钟才能加载您的消息历史记录，尤其是如果您有许多聊天记录。
- **WhatsApp 不同步**：如果您的 WhatsApp 消息与桥接不同步，请删除两个数据库文件（`whatsapp-bridge/store/messages.db` 和 `whatsapp-bridge/store/whatsapp.db`），并重新启动桥接以重新身份验证。
有关 Claude Desktop 集成的其他故障排除信息，请参阅 [MCP 文档](https://modelcontextprotocol.io/quickstart/server#claude-for-desktop-integration-issues)。文档中包含有关检查日志和解决常见问题的有用的提示。
