内容
<div align="center">
# 📱 微信 WhatsApp 集成
**直接从任何 AI 发送消息、图片、文档等到 WhatsApp。**
[](https://python.org)
[](https://modelcontextprotocol.io)
[](LICENSE)
[](https://github.com/gabriellopesdesouza2002/mcp-whatsapp)
与 **Claude**、**Gemini**、**Cursor**、**Windsurf**、**Continue.dev** 和任何 MCP 兼容的 AI 配合使用。
**100% 开源并遵循 MIT 许可。**
</div>
---
## ✨ 功能介绍
与你的 AI 自然对话：
> *"向 +5511999998888 发送消息，内容为会议延期"*
>
> *"向客户群发送 invoice.pdf"*
>
> *"获取我的支持聊天中最近 20 条消息"*
>
> *"创建一个名为 '团队冲刺' 的群组，成员包括以下号码"*
**无需代码，无需手动 API 调用。只需询问。**
---
## 🚀 快速开始（3 步）
### 步骤 1 — 克隆并启动 WuzAPI
```bash
git clone https://github.com/YOUR_USER/mcp-whatsapp
cd mcp-whatsapp
docker compose up -d
```
就这样 — WuzAPI 会在 `http://localhost:7143` 自动启动，并启用消息历史记录。✅
> 包含的 `docker-compose.yml` 会为你设置好一切。
> 默认管理员令牌：`admin123`（可通过 `WUZAPI_ADMIN_TOKEN` 环境变量修改）。
### 步骤 2 — 安装 MCP 服务器
```bash
python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux / macOS
source .venv/bin/activate
pip install -e .
```
### 步骤 3 — 使用 Claude Code 注册（全局，一次性）
```bash
# Windows（替换为你的绝对路径）
claude mcp add whatsapp -s user -- C:\path\to\mcp-whatsapp\.venv\Scripts\python.exe -m mcp_whatsapp.server
# Linux / macOS（替换为你的绝对路径）
claude mcp add whatsapp -s user -- /path/to/mcp-whatsapp/.venv/bin/python -m mcp_whatsapp.server
```
重启 Claude，然后直接询问：
> *"使用令牌 **mytoken123** 配置我的 WhatsApp"*
**魔术：** 服务器会自动在 WuzAPI 中为你创建用户（即插即用）。无需手动后台操作！ 🪄
---
## 🔑 手动配置（可选）
如果你更喜欢使用后台管理界面，它位于 `http://localhost:7143`。
1. 打开 `http://localhost:7143` → 点击 **管理员模式**
2. 输入管理员令牌 — 默认值为 `admin123`
3. 进入 **用户 → 创建用户**，输入任意名称并选择一个令牌。
> *"使用令牌 **myusertoken** 配置我的 WhatsApp"*
> 💡 **两个令牌，两个用途：**
> - **用户令牌** → 发送/接收消息 — 这是你日常使用的令牌
> - **管理员令牌** → 管理用户 — 仅在 `whatsapp_admin_*` 工具中需要
---
## 🔌 连接到你的 AI
### Claude Code（推荐）
```bash
claude mcp add whatsapp -s user -- \
/path/to/.venv/bin/python -m mcp_whatsapp.server
```
然后让 Claude 配置：
> *"配置我的 WhatsApp：token=abc123, url=http://localhost:7143"*
### Claude 桌面版
添加到 `claude_desktop_config.json`:
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"whatsapp": {
"command": "/path/to/mcp-whatsapp/.venv/bin/python",
"args": ["-m", "mcp_whatsapp.server"],
"env": {
"WUZAPI_BASE_URL": "http://localhost:7143",
"WUZAPI_TOKEN": "your_token_here"
}
}
}
}
```
### Cursor / Windsurf / Continue.dev
添加到编辑器的 MCP 配置文件中：
```json
{
"mcpServers": {
"whatsapp": {
"command": "/path/to/mcp-whatsapp/.venv/bin/python",
"args": ["-m", "mcp_whatsapp.server"],
"env": {
"WUZAPI_BASE_URL": "http://localhost:7143",
"WUZAPI_TOKEN": "your_token_here"
}
}
}
}
```
### 任何其他 MCP 兼容的 AI
- **传输：** stdio（标准）
- **命令：** `python -m mcp_whatsapp.server`
- **环境变量：** `WUZAPI_BASE_URL`, `WUZAPI_TOKEN`
---
## 🛠️ 可用工具（30+）
| 类别 | 工具 |
|----------|-------|
| **⚙️ 设置** | `whatsapp_configure` |
| **🔗 会话** | `whatsapp_connect`, `whatsapp_disconnect`, `whatsapp_status`, `whatsapp_get_qrcode`, `whatsapp_health` |
| **💬 消息** | `whatsapp_send_text`, `whatsapp_send_image`, `whatsapp_send_document`, `whatsapp_send_audio`, `whatsapp_send_video`, `whatsapp_send_sticker`, `whatsapp_send_location`, `whatsapp_send_contact`, `whatsapp_send_link`, `whatsapp_send_buttons`, `whatsapp_send_list`, `whatsapp_send_poll` |
| **📥 聊天** | `whatsapp_get_chats`, `whatsapp_get_unread_messages`, `whatsapp_get_messages`, `whatsapp_reply_message`, `whatsapp_delete_message`, `whatsapp_react`, `whatsapp_mark_read`, `whatsapp_download_media`, `whatsapp_search_messages`, `whatsapp_forward_message` |
| **👤 用户** | `whatsapp_get_user_info`, `whatsapp_get_contacts`, `whatsapp_search_contacts`, `whatsapp_check_phones`, `whatsapp_get_avatar` |
| **👥 群组** | `whatsapp_list_groups`, `whatsapp_get_group_info`, `whatsapp_create_group`, `whatsapp_update_group_participants`, `whatsapp_get_group_invite_link` |
| **🔔 Webhook** | `whatsapp_set_webhook` |
| **📢 通讯稿** | `whatsapp_get_newsletter_messages`, `whatsapp_subscribe_newsletter` |
| **🔐 管理员** | `whatsapp_admin_list_users`, `whatsapp_admin_create_user`, `whatsapp_admin_delete_user` |
---
## 💡 使用示例
### 首次设置
```
你： "使用令牌 abc123 配置我的 WhatsApp"
Claude: ✅ 配置已保存！现在使用 whatsapp_connect() 连接。
你： "连接我的 WhatsApp"
Claude: [生成二维码 — 用手机扫描]
你： "检查 WhatsApp 是否已连接"
Claude: ✅ 已连接，号码为 +5511999998888
```
### 发送消息
```
你： "向 +5511999998888 发送 '你好！'"
你： "向销售群发送文件 report.pdf"
你： "向 +5511987654321 发送我的位置"
你： "对 WhatsApp 聊天 5511999998888@s.whatsapp.net 中的最后一条消息做出 👍 反应"
```
### 管理群组
```
你： "列出我所有的 WhatsApp 群组"
你： "创建一个名为 '项目 X' 的群组，成员包括 +5511111111111 和 +5522222222222"
你： "获取群组 120363XXXXXXXX@g.us 的邀请链接"
```
---
## 📞 电话号码格式
WuzAPI 使用的 WhatsApp 号码不带 `+` 前缀：
| 格式 | 有效？ |
|--------|--------|
| `5511999998888` | ✅ 巴西（DDD 11） |
| `14155552671` | ✅ 美国（415） |
| `+5511999998888` | ❌ 删除 `+` |
| `011999998888` | ❌ 使用国家代码 |
---
## 📁 项目结构
```
mcp-whatsapp/
├── pyproject.toml # Python 项目配置
├── .env.example # 环境变量模板
└── src/
└── mcp_whatsapp/
├── server.py # 包含所有工具的 MCP 服务器
└── wuzapi_client.py # WuzAPI 的异步 HTTP 客户端
```
---
## 🛡️ 安全性和合规使用
**重要：本项目使用非官方 WhatsApp API，请自担风险。**
为了确保您的账户安全并遵守全球数据法规（LGPD/GDPR），请遵循以下准则：
1. **避免垃圾信息：** 请勿将此工具用于群发消息或自动化营销。过度的自动化活动是 WhatsApp 账户被封的主要原因。
2. **隐私保护：** 默认情况下，本服务器会对敏感信息（PII）进行掩码处理，如 CPF、信用卡和电子邮件（当 `WUZAPI_PRIVACY_MODE=true` 时）。
3. **审计日志：** 所有工具调用都会记录在 `logs/audit_privacy.log` 中。这对于透明度和责任追究至关重要。
4. **令牌安全：** 请勿分享您的 `WUZAPI_TOKEN` 或 `WUZAPI_ADMIN_TOKEN`。这些令牌授予对您的消息的完全访问权限。
5. **AI 自主性：** 在赋予 AI "自主权" 发送消息时请谨慎。始终审查 AI 执行高风险任务时的输出。
6. **服务条款：** 请注意，使用非官方 API 违反 WhatsApp 的服务条款。本工具旨在用于个人生产力和研究。
---
## 🤝 贡献
欢迎贡献！请随意提出问题和拉取请求。
1. 复刻仓库
2. 创建功能分支（`git checkout -b feature/amazing-feature`）
3. 提交更改
4. 打开拉取请求
---
## 📄 许可证
本项目是开源的，遵循 [MIT 许可证](LICENSE)。
---
<div align="center">
**为 MCP 生态系统构建 ❤️**
如果这个项目对你有帮助，请 ⭐ 给它点赞！
</div>
