内容
# WhatsApp MCP Server
这是一个用于 WhatsApp 的 Model Context Protocol (MCP) server。
有了它，你可以搜索你的个人 Whatsapp 消息，搜索你的联系人并发送消息。
它通过 Whatsapp web multidevice API（使用 [whatsmeow](https://github.com/tulir/whatsmeow) 库）直接连接到你的 **个人 WhatsApp 帐户**。你所有的消息都存储在本地的 SQLite 数据库中，只有当 agent 通过工具（你控制的）访问它们时才发送到 LLM（例如 Claude）。
这是一个连接到 Claude 后你可以做的示例。
## Installation
### Prerequisites
- Go
- Python 3.6+
- Anthropic Claude Desktop app
- UV (Python package manager), install with `curl -LsSf https://astral.sh/uv/install.sh | sh`
### Steps
1. **Clone this repository**
```bash
git clone https://github.com/lharries/whatsapp-mcp.git
cd whatsapp-mcp
```
2. **Run the WhatsApp bridge**
导航到 whatsapp-bridge 目录并运行 Go 应用程序：
```bash
cd whatsapp-bridge
go run main.go
```
第一次运行它时，系统会提示你扫描 QR 码。使用你的 WhatsApp 移动应用程序扫描 QR 码进行身份验证。
大约 20 天后，你可能需要重新进行身份验证。
3. **Connect to Anthropic Claude (optional)**
复制下面的 json，并使用适当的 {{PATH}} 值：
```json
{
"mcpServers": {
"whatsapp": {
"command": "{{PATH}}/.local/bin/uv",
"args": [
"--directory",
"{{PATH}}/whatsapp-mcp/whatsapp-mcp-server",
"run",
"main.py"
]
}
}
}
```
将其另存为 `claude_desktop_config.json` 在你的 Claude Desktop 配置目录中：
```
~/Library/Application Support/Claude/claude_desktop_config.json
```
4. **Restart Claude Desktop**
打开 Claude Desktop，你现在应该看到 WhatsApp 作为可用的集成。
## Architecture Overview
此应用程序由两个主要组件组成：
1. **Go WhatsApp Bridge** (`whatsapp-bridge/`): 一个 Go 应用程序，它连接到 WhatsApp 的 web API，通过 QR 码处理身份验证，并将消息历史记录存储在 SQLite 中。它充当 WhatsApp 和 MCP server 之间的桥梁。
2. **Python MCP Server** (`whatsapp-mcp-server/`): 一个 Python server，实现了 Model Context Protocol (MCP)，它为 Claude 提供了标准化工具，用于与 WhatsApp 数据交互以及发送/接收消息。
### Data Storage
- 所有消息历史记录都存储在 `whatsapp-bridge/store/` 目录中的 SQLite 数据库中
- 数据库维护聊天和消息的表
- 消息被索引以实现高效的搜索和检索
## Usage
连接后，你可以通过 Claude 与你的 WhatsApp 联系人互动，在你的 WhatsApp 对话中利用 Claude 的 AI 功能。
### MCP Tools
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**: 向指定的电话号码发送 WhatsApp 消息
## Technical Details
1. Claude 向 Python MCP server 发送请求
2. MCP server 查询 Go bridge 以获取 WhatsApp 数据或直接查询 SQLite 数据库
3. Go 访问 WhatsApp API 并保持 SQLite 数据库的更新
4. 数据通过链返回到 Claude
5. 发送消息时，请求从 Claude 通过 MCP server 流向 Go bridge 并流向 WhatsApp
## Troubleshooting
- 如果在运行 uv 时遇到权限问题，你可能需要将其添加到你的 PATH 或使用可执行文件的完整路径。
- 确保 Go 应用程序和 Python server 都在运行，以便集成正常工作。
### Authentication Issues
- **QR Code Not Displaying**: 如果未显示 QR 码，请尝试重新启动身份验证脚本。如果问题仍然存在，请检查你的终端是否支持显示 QR 码。
- **WhatsApp Already Logged In**: 如果你的会话已激活，Go bridge 将自动重新连接，而无需显示 QR 码。
- **Device Limit Reached**: WhatsApp 限制了链接设备的数量。如果达到此限制，你需要从手机上的 WhatsApp 中删除现有设备（设置 > 链接设备）。
- **No Messages Loading**: 初始身份验证后，加载消息历史记录可能需要几分钟，尤其是在你有大量聊天记录的情况下。
- **WhatsApp Out of Sync**: 如果你的 WhatsApp 消息与 bridge 不同步，请删除两个数据库文件（`whatsapp-bridge/store/messages.db` 和 `whatsapp-bridge/store/whatsapp.db`）并重新启动 bridge 以重新进行身份验证。
有关其他 Claude Desktop 集成故障排除，请参阅 [MCP documentation](https://modelcontextprotocol.io/quickstart/server#claude-for-desktop-integration-issues)。该文档包括用于检查日志和解决常见问题的有用提示。
MCP 市场
