内容
# WhatsApp MCP Plus
Fork melhorado do [whatsapp-mcp](https://github.com/lharries/whatsapp-mcp) com correcoes criticas e otimizacoes de performance.
## O que há de diferente?
| 功能 | 原始版本 | MCP Plus |
|---------|----------|----------|
| 最近消息（LID） | 找不到 | 自动解决 |
| 查询性能 | 全表扫描 | 优化的SQLite索引 |
| 上下文获取（N+1） | 每次调用61个查询 | 重用打开的连接 |
| 连接 | 断开后不重连 | 自动重连，指数退避 |
| 历史同步 | 手动 | 每30分钟自动 |
| 登录二维码 | 仅终端 | 生成PNG + macOS通知 |
| MCP SDK | v1.6.0 | v1.10.1 |
| 媒体过滤 | 不支持 | 按图片/视频/音频/文档过滤 |
| 健康检查 | 不支持 | GET /api/status |
| 群组名称 | 每个消息1个查询 | 批量查找 |
## 预备条件
- [Go](https://go.dev/dl/) 1.21+
- [Python](https://www.python.org/downloads/) 3.11+
- [uv](https://docs.astral.sh/uv/getting-started/installation/) （Python包管理器）
- [FFmpeg](https://ffmpeg.org/) （可选，用于音频消息）
## 安装
### 1. 克隆仓库
```bash
git clone https://github.com/SEU_USUARIO/whatsapp-mcp-plus.git
cd whatsapp-mcp-plus
```
### 2. 编译桥接器
```bash
cd whatsapp-bridge
go build -o whatsapp-bridge main.go
```
### 3. 初次运行（认证）
```bash
./whatsapp-bridge
```
二维码将出现在终端中。使用WhatsApp扫描：
**WhatsApp > 设置 > 连接设备 > 连接设备**
认证后，会话将被保存。后续运行将自动连接。
### 4. 后续运行（使用脚本）
```bash
cd ..
chmod +x start-bridge.sh
./start-bridge.sh
```
脚本会：
- 终止之前的实例
- 释放端口8080
- 如有必要，生成二维码PNG文件 `/tmp/wa_qrcode.png`
- 发送macOS通知
### 5. 配置MCP客户端
查找 `uv` 的路径：
```bash
which uv
```
#### Claude Code（CLI）
在 `~/.claude/.mcp.json` 中添加：
```json
{
"mcpServers": {
"whatsapp": {
"command": "/CAMINHO/PARA/uv",
"args": [
"--directory",
"/CAMINHO/PARA/whatsapp-mcp-plus/whatsapp-mcp-server",
"run",
"main.py"
]
}
}
}
```
#### Claude Desktop
在 `~/Library/Application Support/Claude/claude_desktop_config.json` 中添加：
```json
{
"mcpServers": {
"whatsapp": {
"command": "/CAMINHO/PARA/uv",
"args": [
"--directory",
"/CAMINHO/PARA/whatsapp-mcp-plus/whatsapp-mcp-server",
"run",
"main.py"
]
}
}
}
```
#### Cursor
在 `~/.cursor/mcp.json` 中添加（格式同上）。
### 6. 重启客户端
重启Claude Desktop、Cursor或Claude Code会话。
## 可用工具
| 工具 | 描述 |
|------|-----------|
| `search_contacts` | 按姓名或号码搜索联系人 |
| `list_messages` | 列出消息，支持按日期、聊天、内容、媒体类型过滤 |
| `list_chats` | 列出聊天记录及最新消息 |
| `get_chat` | 获取聊天元数据，支持按JID查找 |
| `get_direct_chat_by_contact` | 按号码查找直接聊天 |
| `get_contact_chats` | 获取联系人的所有聊天记录 |
| `get_last_interaction` | 获取与联系人的最新消息 |
| `get_message_context` | 获取消息上下文 |
| `send_message` | 发送文本消息 |
| `send_file` | 发送文件（图片、视频、文档） |
| `send_audio_message` | 发送音频消息 |
| `download_media` | 下载消息媒体 |
## 架构
```
WhatsApp Cloud <-> Go Bridge (whatsmeow) <-> SQLite <-> Python MCP Server <-> Claude
|
REST API :8080
/api/send
/api/download
/api/status
```
1. **Go Bridge** 通过 whatsmeow 连接到WhatsApp，并将数据存储在SQLite中。
2. **Python MCP Server** 从SQLite读取数据，并通过MCP协议提供工具。
3. 发送消息时，MCP Server 调用 Bridge的REST API。
## 故障排除
### 消息未显示给联系人
WhatsApp迁移到了LIDs（链接设备ID）。此分支会自动解决。搜索联系人时使用**姓名**，而非号码。
### Bridge断开连接
MCP Plus具有指数退避的自动重连功能。如果问题持续，删除 `whatsapp-bridge/store/` 中的文件并重新认证。
### 二维码未在终端显示
使用 `start-bridge.sh` 生成二维码PNG文件 `/tmp/wa_qrcode.png`。
### Windows编译错误
`go-sqlite3` 需要启用CGO：
```bash
cd whatsapp-bridge
go env -w CGO_ENABLED=1
go build -o whatsapp-bridge.exe main.go
```
需要安装C编译器（例如 [MSYS2](https://www.msys2.org/)）。
### 健康检查
检查Bridge是否运行：
```bash
curl http://localhost:8080/api/status
```
返回： `{"connected": true, "logged_in": true, "timestamp": "..."}`
## License
MIT License. See [LICENSE](LICENSE).
