hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Integrations
Provides a bridge to WhatsApp Web functionality, enabling tools to send/receive messages, search contacts, manage groups, retrieve chat histories, and perform other WhatsApp operations programmatically.
WhatsApp 网页版 MCP
使用模型上下文协议 (MCP) 在 WhatsApp Web 和 AI 模型之间搭建强大的桥梁。该项目使 Claude 等 AI 模型能够通过标准化接口与 WhatsApp 交互，从而轻松实现 WhatsApp 交互的自动化，并增强其编程能力。
概述
WhatsApp Web MCP 通过以下方式实现 WhatsApp Web 与 AI 模型之间的无缝集成：
- 通过模型上下文协议（MCP）创建标准化接口
- 为 MCP 服务器提供对 WhatsApp 功能的访问
- 通过 SSE 或命令模式提供灵活的部署选项
- 支持直接 WhatsApp 客户端集成和基于 API 的连接
免责声明
重要提示：此工具仅用于测试目的，不应在生产环境中使用。
WhatsApp Web 项目的免责声明：
本项目与 WhatsApp 或其任何子公司或关联公司均无关联、关联、授权、认可或任何形式的官方联系。WhatsApp 官方网站为 whatsapp.com。“WhatsApp”及其相关名称、标志、徽标和图像均为其各自所有者的注册商标。此外，我们无法保证您使用此方法不会被屏蔽。WhatsApp 不允许在其平台上使用机器人或非官方客户端，因此此方法并非完全安全。
安装
- 克隆存储库：Copy
- 全局安装或与 npx 一起使用：Copy
- 使用 Docker 构建：Copy
配置
命令行选项
| 选项 | 别名 | 描述 | 选择 | 默认 |
|---|---|---|---|---|
--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 的 API 基 URL | - | http://localhost:3001/api |
--api-key | -k | 使用 API 模式时 WhatsApp Web REST API 的 API 密钥 | - | '' |
API 密钥认证
在 API 模式下运行时，WhatsApp API 服务器需要使用 API 密钥进行身份验证。启动 WhatsApp API 服务器时，API 密钥会自动生成，并显示在日志中：
要将 MCP 服务器连接到 WhatsApp API 服务器，您需要使用--api-key或-k选项提供此 API 密钥：
API 密钥存储在身份验证数据目录中（由--auth-data-path指定），并在 WhatsApp API 服务器重启后仍然存在。
身份验证方法
本地身份验证（推荐）
- 扫描一次二维码
- 凭据在会话之间持续存在
- 长期运行更稳定
无需身份验证
- 默认方法
- 每次启动时都需要扫描二维码
- 适用于测试和开发
用法
运行模式
WhatsApp API 服务器
运行独立的 WhatsApp API 服务器，通过 REST 端点公开 WhatsApp 功能：
MCP 服务器（独立）
运行直接连接到 WhatsApp Web 的 MCP 服务器：
MCP 服务器（API 客户端）
运行连接到 WhatsApp API 服务器的 MCP 服务器：
可用工具
| 工具 | 描述 | 参数 |
|---|---|---|
get_status | 检查 WhatsApp 客户端连接状态 | 没有任何 |
send_message | 向 WhatsApp 联系人发送消息 | number ：要发送的电话号码message ：要发送的文本内容 |
search_contacts | 按姓名或号码搜索联系人 | query ：搜索词来查找联系人 |
get_messages | 从特定聊天中检索消息 | number ：用于获取消息的电话号码limit （可选）：要检索的消息数量 |
get_chats | 获取所有 WhatsApp 聊天列表 | 没有任何 |
create_group | 创建新的 WhatsApp 群组 | name ：群组名称participants ：要添加的电话号码数组 |
add_participants_to_group | 将参与者添加到现有组 | groupId ：群组participants的 ID：要添加的电话号码数组 |
get_group_messages | 从群组中检索消息 | groupId ：群组 ID limit （可选）：要检索的消息数量 |
send_group_message | 向群组发送消息 | groupId ：群组ID 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 | 得到 | 获取 WhatsApp 连接状态 | 没有任何 |
/api/contacts | 得到 | 获取所有联系人 | 没有任何 |
/api/contacts/search | 得到 | 搜索联系人 | query ：搜索词 |
/api/chats | 得到 | 获取所有聊天记录 | 没有任何 |
/api/messages/{number} | 得到 | 从聊天中获取消息 | limit （查询）：消息数量 |
/api/send | 邮政 | 发送消息 | number ：收件人message ：信息内容 |
集团管理
| 端点 | 方法 | 描述 | 参数 |
|---|---|---|---|
/api/groups | 得到 | 获取所有组 | 没有任何 |
/api/groups/search | 得到 | 搜索群组 | query ：搜索词 |
/api/groups/create | 邮政 | 创建新组 | name ：组名participants ：数字数组 |
/api/groups/{groupId} | 得到 | 获取特定组的详细信息 | 没有任何 |
/api/groups/{groupId}/messages | 得到 | 从群组获取消息 | limit （查询）：消息数量 |
/api/groups/{groupId}/participants/add | 邮政 | 向群组添加成员 | participants ：数字数组 |
/api/groups/send | 邮政 | 向群组发送消息 | groupId ：群组ID message ：消息内容 |
人工智能集成
Claude 桌面集成
选项 1：使用 NPX
- 启动 WhatsApp API 服务器：Copy
- 使用 WhatsApp 移动应用扫描二维码
- 请注意日志中显示的 API 密钥：Copy
- 将以下内容添加到您的 Claude Desktop 配置中：Copy
选项 2：使用 Docker
- 在 Docker 中启动 WhatsApp API 服务器：Copy
- 使用 WhatsApp 移动应用扫描二维码
- 请注意日志中显示的 API 密钥：Copy
- 将以下内容添加到您的 Claude Desktop 配置中：Copy
- 重启Claude桌面
- WhatsApp 功能将通过 Claude 的界面提供
建筑学
该项目的结构清晰，关注点分离：
成分
- WhatsAppService ：与 WhatsApp 交互的核心业务逻辑
- WhatsAppApiClient ：用于连接 WhatsApp API 的客户端
- API 路由器：REST API 的快速路由
- MCP 服务器：模型上下文协议实现
部署选项
- WhatsApp API 服务器：独立 REST API 服务器
- MCP 服务器（独立） ：直接连接到 WhatsApp Web
- MCP 服务器（API 客户端） ：连接到 WhatsApp API 服务器
该架构允许灵活的部署场景，包括：
- 在不同的机器上运行 API 服务器和 MCP 服务器
- 使用 MCP 服务器作为现有 API 服务器的客户端
- 为了简单起见，在单台机器上运行所有内容
发展
项目结构
从源代码构建
测试
该项目使用 Jest 进行单元测试。要运行测试，请执行以下操作：
代码检查和格式化
该项目使用 ESLint 和 Prettier 来保证代码质量和格式：
代码检查配置强制执行 TypeScript 最佳实践并在整个项目中保持一致的代码风格。
故障排除
Claude 桌面集成问题
- 在 Claude 上，无法以命令独立模式启动 wweb-mcp，因为 Claude 会多次打开多个进程，并且每个 wweb-mcp 都需要打开一个 Puppeteer 会话，而这些会话无法共享相同的 WhatsApp 身份验证。由于此限制，我们将应用拆分为 MCP 和 API 模式，以便与 Claude 正确集成。
即将推出的功能
- 为传入消息和其他 WhatsApp 事件创建 webhook
- 支持发送媒体文件（图像、音频、文档）
- 群聊管理功能
- 联系人管理（添加/删除联系人）
- 常见场景的消息模板
- 增强错误处理和恢复
贡献
- 分叉存储库
- 创建功能分支
- 提交你的更改
- 推送到你的分支
- 创建拉取请求
请确保您的 PR：
- 遵循现有的代码风格
- 包括适当的测试
- 根据需要更新文档
- 详细描述变化
依赖项
WhatsApp Web.js
本项目使用whatsapp-web.js ，这是一个非官方的 WhatsApp Web JavaScript 客户端库，可通过 WhatsApp Web 浏览器应用进行连接。更多信息，请访问whatsapp-web.js GitHub 代码库。
执照
该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅LICENSE文件。
日志记录
WhatsApp Web MCP 包含一个由 Winston 构建的强大日志系统。该日志系统提供以下功能：
- 多个日志级别（错误、警告、信息、http、调试）
- 带有彩色日志的控制台输出
- API 端点的 HTTP 请求/响应日志记录
- 结构化错误处理
- 环境感知日志级别（开发与生产）
- 在 MCP 命令模式下运行时，所有日志都定向到 stderr
日志级别
该应用程序支持以下日志级别（按详细程度排序）：
- 错误- 导致应用程序无法运行的严重错误
- 警告- 不会停止应用程序但需要注意的警告
- 信息- 有关应用程序状态和事件的一般信息
- http - HTTP 请求/响应日志记录
- debug - 详细的调试信息
配置日志级别
您可以在启动应用程序时使用--log-level或-l标志配置日志级别：
或者使用全局安装时：
命令模式日志记录
在 MCP 命令模式 ( --mode mcp --transport command ) 下运行时，所有日志都会定向到 stderr。这对于命令行工具来说非常重要，因为 stdout 可能用于数据输出，而 stderr 则用于日志记录和诊断。这确保了通过 stdout 进行的 MCP 协议通信不会受到日志消息的干扰。
测试环境
在测试环境中（当NODE_ENV=test或使用 Jest 运行时），记录器会自动调整其行为以适合测试环境。
This server cannot be installed
使用模型上下文协议将 WhatsApp Web 连接到 AI 模型的桥梁，使 Claude 和其他 AI 系统能够通过标准化接口与 WhatsApp 进行交互。