内容
# WhatsApp 网页版 MCP
一款使用模型上下文协议（MCP）连接 WhatsApp 网页版与 AI 模型的强大桥梁。该项目使 Claude 等 AI 模型能够通过标准化的接口与 WhatsApp 交互，从而轻松实现 WhatsApp 交互的自动化和增强。
## 概述
WhatsApp 网页版 MCP 通过以下方式提供 WhatsApp 网页版与 AI 模型的无缝集成：
- 通过模型上下文协议（MCP）创建标准化接口
- 提供 MCP 服务器访问 WhatsApp 功能
- 通过 SSE 或命令行模式提供灵活的部署选项
- 支持直接的 WhatsApp 客户端集成和基于 API 的连接
## 免责声明
**重要**：本工具仅用于测试目的，不应在生产环境中使用。
WhatsApp 网页版项目的免责声明：
> 本项目与 WhatsApp 或其任何子公司或关联公司无关，不以任何方式获得 WhatsApp 或其关联公司的官方认可或授权。官方 WhatsApp 网站可访问 https://www.whatsapp.com。WhatsApp 以及相关名称、标志、徽标和图像是其各自所有者的注册商标。同时，不能保证使用此方法不会被阻止。WhatsApp 不允许在其平台上使用机器人或非官方客户端，因此本工具的安全性不能保证。
## 安装
1. 克隆仓库：
```bash
git clone https://github.com/pnizer/wweb-mcp.git
cd wweb-mcp
```
2. 全局安装或使用 npx：
```bash
# 全局安装
npm install -g .
# 或使用 npx 直接运行
npx .
```
3. 使用 Docker 构建：
```bash
docker build . -t wweb-mcp:latest
```
## 配置
### 命令行选项
| 选项 | 别名 | 描述 | 选择 | 默认值 |
|--------|-------|-------------|---------|---------|
| `--mode` | `-m` | 运行模式 | `mcp`, `whatsapp-api` | `mcp` |
| `--mcp-mode` | `-c` | MCP 连接模式 | `standalone`, `api` | `standalone` |
| `--transport` | `-t` | MCP 传输模式 | `sse`, `command` | `sse` |
| `--sse-port` | `-p` | SSE 服务器端口 | - | `3002` |
| `--api-port` | - | WhatsApp API 服务器端口 | - | `3001` |
| `--auth-data-path` | `-a` | 存储身份验证数据路径 | - | `.wwebjs_auth` |
| `--auth-strategy` | `-s` | 身份验证策略 | `local`, `none` | `local` |
| `--api-base-url` | `-b` | 使用 api 模式时的 MCP 基本 URL | - | `http://localhost:3001/api` |
| `--api-key` | `-k` | 使用 api 模式时的 WhatsApp Web REST API 密钥 | - | `''` |
### API 密钥身份验证
在 API 模式下运行 WhatsApp API 服务器时，需要使用 API 密钥进行身份验证。API 密钥在启动 WhatsApp API 服务器时自动生成，并在日志中显示：
```
WhatsApp API 密钥：1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
```
要将 MCP 服务器连接到 WhatsApp API 服务器，需要使用 `--api-key` 或 `-k` 选项提供此 API 密钥：
```bash
npx wweb-mcp --mode mcp --mcp-mode api --api-base-url http://localhost:3001/api --api-key 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
```
API 密钥存储在身份验证数据目录（由 `--auth-data-path` 指定）中，并在 WhatsApp API 服务器重启后持续存在。
### 身份验证方法
#### 本地身份验证（推荐）
- 扫描一次二维码
- 凭证在会话之间持续存在
- 更稳定，适合长期运行
#### 无身份验证
- 默认方法
- 每次启动时需要扫描二维码
- 适合测试和开发
## 用法
### 运行模式
#### WhatsApp API 服务器
运行一个独立的 WhatsApp API 服务器，通过 REST 端点公开 WhatsApp 功能：
```bash
npx wweb-mcp --mode whatsapp-api --api-port 3001
```
#### MCP 服务器（独立）
运行一个直接连接到 WhatsApp 网页版的 MCP 服务器：
```bash
npx wweb-mcp --mode mcp --mcp-mode standalone --transport sse --sse-port 3002
```
#### MCP 服务器（API 客户端）
运行一个连接到 WhatsApp API 服务器的 MCP 服务器：
```bash
# 首先启动 WhatsApp API 服务器并记录日志中的 API 密钥
npx wweb-mcp --mode whatsapp-api --api-port 3001
# 然后使用 API 密钥启动 MCP 服务器
npx wweb-mcp --mode mcp --mcp-mode api --api-base-url http://localhost:3001/api --api-key YOUR_API_KEY --transport sse --sse-port 3002
```
### 可用工具
| 工具 | 描述 | 参数 |
|------|-------------|------------|
| `get_status` | 检查 WhatsApp 客户端连接状态 | 无 |
| `send_message` | 向 WhatsApp 联系人发送消息 | `number`: 发送到的电话号码<br>`message`: 要发送的文本内容 |
| `search_contacts` | 按姓名或号码搜索联系人 | `query`: 搜索联系人的搜索词 |
| `get_messages` | 从特定聊天中检索消息 | `number`: 获取消息的电话号码<br>`limit`（可选）：要检索的消息数量 |
| `get_chats` | 获取所有 WhatsApp 聊天列表 | 无 |
| `create_group` | 创建新的 WhatsApp 群组 | `name`: 群组名称<br>`participants`: 要添加的电话号码数组 |
| `add_participants_to_group` | 将参与者添加到现有群组 | `groupId`: 群组 ID<br>`participants`: 要添加的电话号码数组 |
| `get_group_messages` | 从群组中检索消息 | `groupId`: 群组 ID<br>`limit`（可选）：要检索的消息数量 |
| `send_group_message` | 向群组发送消息 | `groupId`: 群组 ID<br>`message`: 要发送的文本内容 |
| `search_groups` | 按名称、描述或成员名称搜索群组 | `query`: 搜索群组的搜索词 |
| `get_group_by_id` | 获取特定群组的详细信息 | `groupId`: 要获取的群组 ID |
### 可用资源
| 资源 URI | 描述 |
|--------------|-------------|
| `whatsapp://contacts` | 所有 WhatsApp 联系人列表 |
| `whatsapp://messages/{number}` | 来自特定聊天的消息 |
| `whatsapp://chats` | 所有 WhatsApp 聊天列表 |
| `whatsapp://groups` | 所有 WhatsApp 群组列表 |
| `whatsapp://groups/search` | 按名称、描述或成员名称搜索群组 |
| `whatsapp://groups/{groupId}/messages` | 来自特定群组的消息 |
### REST API 端点
#### 联系人和消息
| 端点 | 方法 | 描述 | 参数 |
|----------|--------|-------------|------------|
| `/api/status` | GET | 获取 WhatsApp 连接状态 | 无 |
| `/api/contacts` | GET | 获取所有联系人 | 无 |
| `/api/contacts/search` | GET | 搜索联系人 | `query`: 搜索词 |
| `/api/chats` | GET | 获取所有聊天 | 无 |
| `/api/messages/{number}` | GET | 从聊天中获取消息 | `limit`（查询）：消息数量 |
| `/api/send` | POST | 发送消息 | `number`: 收件人<br>`message`: 消息内容 |
#### 群组管理
| 端点 | 方法 | 描述 | 参数 |
|----------|--------|-------------|------------|
| `/api/groups` | GET | 获取所有群组 | 无 |
| `/api/groups/search` | GET | 搜索群组 | `query`: 搜索词 |
| `/api/groups/create` | POST | 创建新群组 | `name`: 群组名称<br>`participants`: 号码数组 |
| `/api/groups/{groupId}` | GET | 获取特定群组的详细信息 | 无 |
| `/api/groups/{groupId}/messages` | GET | 从群组获取消息 | `limit`（查询）：消息数量 |
| `/api/groups/{groupId}/participants/add` | POST | 将成员添加到群组 | `participants`: 号码数组 |
| `/api/groups/send` | POST | 向群组发送消息 | `groupId`: 群组 ID<br>`message`: 消息内容 |
### AI 集成
#### Claude 桌面版集成
##### 选项 1：使用 NPX
1. 启动 WhatsApp API 服务器：
```bash
npx wweb-mcp -m whatsapp-api -s local
```
2. 使用 WhatsApp 移动应用扫描二维码
3. 记录日志中显示的 API 密钥：
```
WhatsApp API 密钥：1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
```
4. 将以下内容添加到您的 Claude 桌面版配置中：
```json
{
"mcpServers": {
"whatsapp": {
"command": "npx",
"args": [
"wweb-mcp",
"-m", "mcp",
"-s", "local",
"-c", "api",
"-t", "command",
"--api-base-url", "http://localhost:3001/api",
"--api-key", "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
]
}
}
}
```
##### 选项 2：使用 Docker
1. 在 Docker 中启动 WhatsApp API 服务器：
```bash
docker run -i -p 3001:3001 -v wweb-mcp:/wwebjs_auth --rm wweb-mcp:latest -m whatsapp-api -s local -a /wwebjs_auth
```
2. 使用 WhatsApp 移动应用扫描二维码
3. 记录日志中显示的 API 密钥：
```
WhatsApp API 密钥：1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
```
4. 将以下内容添加到您的 Claude 桌面版配置中：
```json
{
"mcpServers": {
"whatsapp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"wweb-mcp:latest",
"-m", "mcp",
"-s", "local",
"-c", "api",
"-t", "command",
"--api-base-url", "http://host.docker.internal:3001/api",
"--api-key", "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
]
}
}
}
```
5. 重启 Claude 桌面版
6. WhatsApp 功能将通过 Claude 的界面可用
## 架构
该项目结构清晰，关注点分离：
### 组件
1. **WhatsAppService**：与 WhatsApp 交互的核心业务逻辑
2. **WhatsAppApiClient**：连接 WhatsApp API 的客户端
3. **API Router**：REST API 的 Express 路由
4. **MCP Server**：模型上下文协议实现
### 部署选项
1. **WhatsApp API 服务器**：独立的 REST API 服务器
2. **MCP 服务器（独立）**：直接连接到 WhatsApp 网页版
3. **MCP 服务器（API 客户端）**：连接到 WhatsApp API 服务器
此架构允许灵活的部署场景，包括：
- 在不同机器上运行 API 服务器和 MCP 服务器
- 使用 MCP 服务器作为现有 API 服务器的客户端
- 为简单起见，将所有内容运行在一台机器上
## 开发
### 项目结构
```
src/
├── whatsapp-client.ts # WhatsApp 网页版客户端实现
├── whatsapp-service.ts # 核心业务逻辑
├── whatsapp-api-client.ts # WhatsApp API 客户端
├── api.ts # REST API 路由
├── mcp-server.ts # MCP 协议实现
└── main.ts # 应用程序入口点
```
### 从源码构建
```bash
npm run build
```
### 测试
该项目使用 Jest 进行单元测试。要运行测试：
```bash
# 运行所有测试
npm test
# 在开发过程中以监视模式运行测试
npm run test:watch
# 生成测试覆盖率报告
npm run test:coverage
```
### linting 和格式化
该项目使用 ESLint 和 Prettier 进行代码质量和格式化：
```bash
# 运行 linter
npm run lint
# 自动修复 linting 问题
npm run lint:fix
# 使用 Prettier 格式化代码
npm run format
# 验证代码（linting + 测试）
npm run validate
```
linting 配置强制执行 TypeScript 最佳实践并在整个项目中保持一致的代码风格。
## 故障排除
### Claude 桌面版集成问题
- 由于 Claude 打开多个进程多次，每个 wweb-mcp 需要打开一个 puppeteer 会话，无法共享相同的 WhatsApp 身份验证。因此，我们将应用程序分为 MCP 和 API 模式，以便与 Claude 正确集成。
## 即将到来的功能
- 为传入的消息和其他 WhatsApp 事件创建 webhook
- 支持发送媒体文件（图像、音频、文档）
- 群组聊天管理功能
- 联系人管理（添加/删除联系人）
- 常见场景的消息模板
- 增强的错误处理和恢复
## 贡献
1. 分叉仓库
2. 创建功能分支
3. 提交更改
4. 推送到您的分支
5. 创建拉取请求
请确保您的拉取请求：
- 遵循现有的代码风格
- 包括适当的测试
- 根据需要更新文档
- 详细描述更改
## 依赖
### WhatsApp Web.js
该项目使用 [whatsapp-web.js](https://github.com/pedroslopez/whatsapp-web.js)，一个通过 WhatsApp 网页版连接的非官方 JavaScript 客户端库。有关更多信息，请访问 [whatsapp-web.js GitHub 仓库](https://github.com/pedroslopez/whatsapp-web.js)。
## 许可证
该项目在 MIT 许可证下获得许可 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。
## 日志
WhatsApp 网页版 MCP 包含一个使用 Winston 构建的强大日志系统。日志系统提供：
- 多个日志级别（错误、警告、信息、HTTP、调试）
- 带有颜色日志的控制台输出
- API 端点的 HTTP 请求/响应日志记录
- 结构化错误处理
- 环境感知日志级别（开发 vs. 生产）
- 所有日志在命令行模式下定向到 stderr
### 日志级别
应用程序支持以下日志级别，按详细程度排序：
1. **错误** - 防止应用程序正常运行的严重错误
2. **警告** - 不会停止应用程序但需要关注的警告
3. **信息** - 应用程序状态和事件的一般信息
4. **HTTP** - HTTP 请求/响应日志记录
5. **调试** - 详细的调试信息
### 配置日志级别
您可以在启动应用程序时使用 `--log-level` 或 `-l` 标志配置日志级别：
```bash
npm start -- --log-level=debug
```
或使用全局安装：
```bash
wweb-mcp --log-level=debug
```
### 命令模式日志记录
当以命令模式 (`--mode mcp --transport command`) 运行 MCP 时，所有日志都定向到 stderr。这对于命令行工具很重要，其中 stdout 可能用于数据输出，而 stderr 用于日志记录和诊断。这确保 stdout 上的 MCP 协议通信不会被日志消息干扰。
### 测试环境
在测试环境中（当 `NODE_ENV=test` 或使用 Jest 运行测试时），日志记录器会自动调整其行为以适应测试环境。
MCP 市场
