内容
# WhatsApp MCP适用于Claude Desktop
连接Claude Desktop到WhatsApp。发送和接收消息，管理群组，分享媒体 — 所有这些都通过与Claude的自然对话。
## 功能
- **零配置首次启动** — 自动从Chrome检测您的WhatsApp Web会话
- **多账户支持** — 在多个WhatsApp账户之间切换
- **完整的消息功能** — 发送、读取、搜索、回复、转发、反应
- **媒体支持** — 发送图片/文档，下载附件
- **群组管理** — 创建群组，添加/删除成员，获取信息
- **跨平台支持** — Windows，macOS，Linux
- **自动重连** — 自动从断开连接中恢复
## 快速安装
### Windows
```powershell
git clone https://github.com/Shloimy15e/whatsapp-mcp.git
cd whatsapp-mcp
powershell -ExecutionPolicy Bypass -File install.ps1
```
### macOS / Linux
```bash
git clone https://github.com/Shloimy15e/whatsapp-mcp.git
cd whatsapp-mcp
chmod +x install.sh && ./install.sh
```
### 手动安装
1. 克隆此仓库并进入其中
2. 运行 `PUPPETEER_SKIP_DOWNLOAD=true npm install`
3. 将以下内容添加到您的Claude Desktop配置（`claude_desktop_config.json`）：
```json
{
"mcpServers": {
"whatsapp": {
"command": "node",
"args": ["/full/path/to/whatsapp-mcp/server.mjs"]
}
}
}
```
4. 重启Claude Desktop
## 要求
- **Node.js** 18+（[下载](https://nodejs.org)）
- **Google Chrome** （用于WhatsApp Web引擎）
- **Claude Desktop** （[下载](https://claude.ai/download)）
## 工作原理
在首次启动时，MCP服务器：
1. 扫描您的Chrome配置文件以查找现有的WhatsApp Web会话
2. 如果找到，会克隆会话数据，以便Chrome无需保持打开状态
3. 无头连接到WhatsApp（无可见浏览器窗口）
4. 如果未找到会话，您可以要求Claude通过二维码设置新会话
## 可用工具
| 工具 | 描述 |
|------|-------------|
| `whatsapp_setup` | 管理配置文件（添加、删除、切换、扫描Chrome、克隆会话） |
| `whatsapp_status` | 连接状态、运行时间、平台信息 |
| `whatsapp_list_chats` | 列出最近的聊天记录和未读计数 |
| `whatsapp_read_messages` | 读取聊天记录中的消息 |
| `whatsapp_search_chats` | 按名称或号码搜索聊天记录 |
| `whatsapp_send_message` | 发送文本、回复或媒体消息 |
| `whatsapp_react` | 用表情符号反应消息 |
| `whatsapp_forward_message` | 将消息转发到另一个聊天记录 |
| `whatsapp_download_media` | 下载媒体附件 |
| `whatsapp_get_contact_info` | 获取联系人详细信息 |
| `whatsapp_get_group_info` | 获取群组详细信息和参与者 |
| `whatsapp_create_group` | 创建新群组 |
| `whatsapp_group_add_participants` | 将成员添加到群组 |
| `whatsapp_group_remove_participants` | 从群组中删除成员 |
| `whatsapp_leave_group` | 离开群组 |
## 项目结构
```
whatsapp-mcp/
├── server.mjs # 入口点 — MCP服务器设置和自动连接
├── lib/
│ ├── logger.mjs # 日志记录和崩溃处理程序
│ ├── platform.mjs # 跨平台助手（Chrome路径、操作系统实用程序）
│ ├── config.mjs # 配置文件管理
│ ├── chrome.mjs # Chrome配置文件检测
│ ├── clone.mjs # 从Chrome克隆会话
│ └── client.mjs # WhatsApp客户端生命周期和状态
├── tools/
│ ├── setup.mjs # 配置文件管理工具
│ ├── status.mjs # 连接状态工具
│ ├── chat.mjs # 聊天工具（列表、读取、搜索、发送）
│ ├── media.mjs # 媒体工具（反应、转发、下载）
│ ├── contact.mjs # 联系人信息工具
│ └── group.mjs # 群组管理工具
├── install.ps1 # Windows安装程序
├── install.sh # macOS/Linux安装程序
├── package.json
└── config.json # 自动生成的配置文件
```
## 故障排除
**"未找到Chrome"** — 安装Google Chrome，或在`lib/platform.mjs`中手动设置路径。
**二维码无法扫描** — 确保Chrome完全关闭（检查任务管理器/活动监视器）。WhatsApp Web引擎需要独家访问。
**"WhatsApp未就绪"** — 要求Claude运行`whatsapp_status`获取详细信息。尝试`whatsapp_setup switch_profile name:default`重新连接。
**会话过期** — WhatsApp会话在约2周不活动后过期。删除`.wwebjs_auth`文件夹并重新认证。
## 许可证
MIT
