WhatsApp 网页版 MCP

PR 检查

一个 Node.js 应用程序，通过模型上下文协议 (MCP) 将 WhatsApp Web 与 AI 模型连接起来。该项目提供了一个标准化接口，用于与 WhatsApp 进行编程交互，并通过 AI 驱动的工作流实现自动消息传递、联系人管理和群聊功能。

概述

WhatsApp Web MCP 通过以下方式实现 WhatsApp Web 与 AI 模型之间的无缝集成：

通过模型上下文协议（MCP）创建标准化接口
为 MCP 服务器提供对 WhatsApp 功能的访问
通过 SSE 或命令模式提供灵活的部署选项
支持直接 WhatsApp 客户端集成和基于 API 的连接

Related MCP server: MCP Evolution API

免责声明

重要提示：此工具仅用于测试目的，不应在生产环境中使用。

WhatsApp Web 项目的免责声明：

本项目与 WhatsApp 或其任何子公司或关联公司均无关联、关联、授权、认可或任何形式的官方联系。WhatsApp 官方网站为 whatsapp.com。“WhatsApp”及其相关名称、标志、徽标和图像均为其各自所有者的注册商标。此外，我们无法保证您使用此方法不会被屏蔽。WhatsApp 不允许在其平台上使用机器人或非官方客户端，因此此方法并非完全安全。

学习资源

要了解有关在实际场景中使用 WhatsApp Web MCP 的更多信息，请查看以下文章：

安装

克隆存储库：
git clone https://github.com/pnizer/wweb-mcp.git cd wweb-mcp
全局安装或与 npx 一起使用：
# Install globally npm install -g . # Or use with npx directly npx .
使用 Docker 构建：
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 的 API 基 URL	-	`http://localhost:3001/api`
`--api-key`	`-k`	使用 API 模式时 WhatsApp Web REST API 的 API 密钥	-	`''`

API 密钥认证

在 API 模式下运行时，WhatsApp API 服务器需要使用 API 密钥进行身份验证。启动 WhatsApp API 服务器时，API 密钥会自动生成，并显示在日志中：

WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

要将 MCP 服务器连接到 WhatsApp API 服务器，您需要使用--api-key或-k选项提供此 API 密钥：

npx wweb-mcp --mode mcp --mcp-mode api --api-base-url http://localhost:3001/api --api-key 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

API 密钥存储在身份验证数据目录中（由--auth-data-path指定），并在 WhatsApp API 服务器重启后仍然存在。

身份验证方法

本地身份验证（推荐）

扫描一次二维码
凭据在会话之间持续存在
长期运行更稳定

无需身份验证

默认方法
每次启动时都需要扫描二维码
适用于测试和开发

Webhook 配置

您可以通过在身份验证数据目录（由--auth-data-path指定）中创建webhook.json文件来配置 webhook 以接收传入的 WhatsApp 消息。

Webhook JSON 格式

{ "url": "https://your-webhook-endpoint.com/incoming", "authToken": "your-optional-authentication-token", "filters": { "allowedNumbers": ["+1234567890", "+0987654321"], "allowPrivate": true, "allowGroups": false } }

配置选项

选项	类型	描述
`url`	细绳	将发送消息数据的 webhook 端点 URL
`authToken`	字符串（可选）	身份验证令牌将作为 Bearer 令牌包含在授权标头中
`filters.allowedNumbers`	数组（可选）	接收短信的电话号码列表。如果提供，则只有来自这些号码的短信才会触发 webhook
`filters.allowPrivate`	布尔值（可选）	是否向 webhook 发送私信。默认值： `true`
`filters.allowGroups`	布尔值（可选）	是否将群组消息发送到 webhook。默认值： `true`

Webhook 有效负载

当收到消息并通过过滤器时，将向配置的 URL 发送一个 POST 请求，其中包含以下 JSON 有效负载：

{ "from": "+1234567890", "name": "Contact Name", "message": "Hello, world!", "isGroup": false, "timestamp": 1621234567890, "messageId": "ABCDEF1234567890" }

用法

运行模式

WhatsApp API 服务器

运行独立的 WhatsApp API 服务器，通过 REST 端点公开 WhatsApp 功能：

npx wweb-mcp --mode whatsapp-api --api-port 3001

MCP 服务器（独立）

运行直接连接到 WhatsApp Web 的 MCP 服务器：

npx wweb-mcp --mode mcp --mcp-mode standalone --transport sse --sse-port 3002

MCP 服务器（API 客户端）

运行连接到 WhatsApp API 服务器的 MCP 服务器：

# First, start the WhatsApp API server and note the API key from the logs npx wweb-mcp --mode whatsapp-api --api-port 3001 # Then, start the MCP server with the API key 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` ：要发送的电话号码 `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
`download_media_from_message`	从消息中下载媒体	`messageId` ：包含要下载的媒体的消息的 ID
`send_media_message`	向 WhatsApp 联系人发送媒体消息	`number` ：要发送到的电话号码 `source` ：具有 URI 方案的媒体源（对 URL 使用 `http://` 或 `https://` ，对本地文件使用 `file://` ） `caption` （可选）：媒体的文本标题

可用资源

资源 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/send/media`	邮政	发送媒体消息	`number` ：接收者 `source` ：具有 URI 方案的媒体源（对于 URL 使用 `http://` 或 `https://` ，对于本地文件使用 `file://` ） `caption` （可选）：文本标题
`/api/messages/{messageId}/media/download`	邮政	从消息中下载媒体	没有任何

集团管理

端点	方法	描述	参数
`/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 服务器：
npx wweb-mcp -m whatsapp-api -s local
使用 WhatsApp 移动应用扫描二维码
请注意日志中显示的 API 密钥：
WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
将以下内容添加到您的 Claude Desktop 配置中：
{ "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

在 Docker 中启动 WhatsApp API 服务器：
docker run -i -p 3001:3001 -v wweb-mcp:/wwebjs_auth --rm wweb-mcp:latest -m whatsapp-api -s local -a /wwebjs_auth
使用 WhatsApp 移动应用扫描二维码
请注意日志中显示的 API 密钥：
WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
将以下内容添加到您的 Claude Desktop 配置中：
{ "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" ] } } }
重启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 服务器的客户端
为了简单起见，在单台机器上运行所有内容

发展

项目结构

src/ ├── whatsapp-client.ts # WhatsApp Web client implementation ├── whatsapp-service.ts # Core business logic ├── whatsapp-api-client.ts # Client for the WhatsApp API ├── api.ts # REST API router ├── mcp-server.ts # MCP protocol implementation └── main.ts # Application entry point

从源代码构建

npm run build

测试

该项目使用 Jest 进行单元测试。要运行测试，请执行以下操作：

# Run all tests npm test # Run tests in watch mode during development npm run test:watch # Generate test coverage report npm run test:coverage

代码检查和格式化

该项目使用 ESLint 和 Prettier 来保证代码质量和格式：

# Run linter npm run lint # Fix linting issues automatically npm run lint:fix # Format code with Prettier npm run format # Validate code (lint + test) npm run validate

代码检查配置强制执行 TypeScript 最佳实践并在整个项目中保持一致的代码风格。

出版

该项目使用 GitHub Actions 自动发布到 npm。工作流程处理：

版本递增（ patch 、 minor或major ）
Git 标记版本以“v”为前缀（例如，v0.2.1）
使用 GitHub secrets 发布到 npm

要发布新版本：

前往 GitHub 存储库的“Actions”选项卡
选择“发布包”工作流程
点击“运行工作流程”
选择版本增量类型（补丁、次要版本或主要版本）
点击“运行工作流程”开始发布过程

此工作流程需要在您的 GitHub 存储库中配置 NPM_TOKEN 机密。

故障排除

Claude 桌面集成问题

在 Claude 上，无法以命令独立模式启动 wweb-mcp，因为 Claude 会多次打开多个进程，并且每个 wweb-mcp 都需要打开一个 Puppeteer 会话，而这些会话无法共享相同的 WhatsApp 身份验证。由于此限制，我们将应用拆分为 MCP 和 API 模式，以便与 Claude 正确集成。

特征

发送和接收消息
发送媒体信息（仅限图像）
从消息中下载媒体（图像、音频、文档）
群聊管理
联系人管理和搜索
消息历史记录检索

即将推出的功能

支持发送所有媒体文件类型（视频、音频、文档）
增强常见场景的消息模板
高级群组管理功能
联系人管理（添加/删除联系人）
增强错误处理和恢复

贡献

分叉存储库
创建功能分支
提交你的更改
推送到你的分支
创建拉取请求

请确保您的 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标志配置日志级别：

npm start -- --log-level=debug

或者使用全局安装时：

wweb-mcp --log-level=debug

命令模式日志记录

在 MCP 命令模式 ( --mode mcp --transport command ) 下运行时，所有日志都会定向到 stderr。这对于命令行工具来说非常重要，因为 stdout 可能用于数据输出，而 stderr 则用于日志记录和诊断。这确保了通过 stdout 进行的 MCP 协议通信不会受到日志消息的干扰。

测试环境

在测试环境中（当NODE_ENV=test或使用 Jest 运行时），记录器会自动调整其行为以适合测试环境。