WhatsApp Web MCP

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

概述

WhatsApp Web MCP 通过以下方式提供 WhatsApp Web 和 AI 模型之间的无缝集成：

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

免责声明

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

来自 WhatsApp Web 项目的免责声明：

本项目与 WhatsApp 或其任何子公司或附属公司没有任何关联、联系、授权、认可或以任何方式正式连接。 官方 WhatsApp 网站可以在 whatsapp.com 找到。“WhatsApp”以及相关名称、标记、徽标和图像是其各自所有者的注册商标。 此外，不能保证您在使用此方法时不会被阻止。 WhatsApp 不允许在其平台上使用机器人或非官方客户端，因此不应认为这是完全安全的。

学习资源

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

• 将 WhatsApp 与 AI 集成：设置 WhatsApp MCP 服务器指南
• 将 OpenAI Agents Python SDK 与 Anthropic 的 MCP 集成

安装

1. 克隆存储库：

   git clone https://github.com/pnizer/wweb-mcp.git
   cd wweb-mcp
   

2. 全局安装或与 npx 一起使用：

   # 全局安装
   npm install -g .
   
   # 或直接与 npx 一起使用
   npx .
   

3. 使用 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	String	将发送消息数据的 Webhook 端点 URL
authToken	String (可选)	要包含在 Authorization 标头中作为 Bearer 令牌的身份验证令牌
filters.allowedNumbers	Array (可选)	接受消息的电话号码列表。 如果提供，则只有来自这些号码的消息才会触发 Webhook
filters.allowPrivate	Boolean (可选)	是否将私人消息发送到 Webhook。 默认值：true
filters.allowGroups	Boolean (可选)	是否将群组消息发送到 Webhook。 默认值：true

Webhook Payload

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

{
  "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 服务器：

# 首先，启动 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 客户端连接状态	None
send_message	向 WhatsApp 联系人发送消息	number: 要发送到的电话号码<br>message: 要发送的文本内容
search_contacts	按姓名或号码搜索联系人	query: 查找联系人的搜索词
get_messages	从特定聊天中检索消息	number: 要从中获取消息的电话号码<br>limit (可选): 要检索的消息数
get_chats	获取所有 WhatsApp 聊天的列表	None
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
download_media_from_message	从消息中下载媒体	messageId: 包含要下载的媒体的消息 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 连接状态	None
/api/contacts	GET	获取所有联系人	None
/api/contacts/search	GET	搜索联系人	query: 搜索词
/api/chats	GET	获取所有聊天	None
/api/messages/{number}	GET	获取来自聊天的消息	limit (query): 消息数
/api/send	POST	发送消息	number: 接收者<br>message: 消息内容
/api/messages/{messageId}/media/download	POST	从消息中下载媒体	None

群组管理

端点	方法	描述	参数
/api/groups	GET	获取所有群组	None
/api/groups/search	GET	搜索群组	query: 搜索词
/api/groups/create	POST	创建一个新群组	name: 群组名称<br>participants: 数字数组
/api/groups/{groupId}	GET	获取有关特定群组的详细信息	None
/api/groups/{groupId}/messages	GET	获取来自群组的消息	limit (query): 消息数
/api/groups/{groupId}/participants/add	POST	将成员添加到群组	participants: 数字数组
/api/groups/send	POST	向群组发送消息	groupId: 群组 ID<br>message: 消息内容

AI 集成

Claude Desktop 集成

选项 1：使用 NPX

1. 启动 WhatsApp API 服务器：

   npx wweb-mcp -m whatsapp-api -s local
   

2. 使用您的 WhatsApp 移动应用程序扫描二维码

3. 记下日志中显示的 API 密钥：

   WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
   

4. 将以下内容添加到您的 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

1. 在 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
   

2. 使用您的 WhatsApp 移动应用程序扫描二维码

3. 记下日志中显示的 API 密钥：

   WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
   

4. 将以下内容添加到您的 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"
               ]
           }
       }
   }
   

5. 重新启动 Claude Desktop

6. WhatsApp 功能将通过 Claude 的界面提供

架构

该项目结构清晰，关注点分离：

组件

1. WhatsAppService: 与 WhatsApp 交互的核心业务逻辑
2. WhatsAppApiClient: 用于连接到 WhatsApp API 的客户端
3. API Router: REST API 的 Express 路由
4. MCP Server: 模型上下文协议实现

部署选项

1. WhatsApp API Server: 独立的 REST API 服务器
2. MCP Server (Standalone): 直接连接到 WhatsApp Web
3. MCP Server (API Client): 连接到 WhatsApp API 服务器

这种架构允许灵活的部署方案，包括：

• 在不同的机器上运行 API 服务器和 MCP 服务器
• 将 MCP 服务器用作现有 API 服务器的客户端
• 在单台机器上运行所有内容以简化操作

开发

项目结构

src/
├── whatsapp-client.ts     # WhatsApp Web 客户端实现
├── whatsapp-service.ts    # 核心业务逻辑
├── whatsapp-api-client.ts # WhatsApp API 的客户端
├── api.ts                 # REST API 路由器
├── mcp-server.ts          # MCP 协议实现
└── main.ts                # 应用程序入口点

从源代码构建

npm run build

测试

该项目使用 Jest 进行单元测试。 要运行测试：

# 运行所有测试
npm test

# 在开发期间以监视模式运行测试
npm run test:watch

# 生成测试覆盖率报告
npm run test:coverage

Linting 和格式化

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

# 运行 linter
npm run lint

# 自动修复 linting 问题
npm run lint:fix

# 使用 Prettier 格式化代码
npm run format

# 验证代码（lint + 测试）
npm run validate

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

发布

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

1. 版本递增 (patch、minor 或 major)
2. 使用 'v' 作为前缀的版本进行 Git 标记（例如，v0.2.1）
3. 使用 GitHub 密钥发布到 npm

要发布新版本：

1. 转到 GitHub 存储库的 Actions 选项卡
2. 选择“Publish Package”工作流程
3. 单击“Run workflow”
4. 选择版本递增类型（patch、minor 或 major）
5. 单击“Run workflow”以启动发布过程

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

故障排除

Claude Desktop 集成问题

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

特性

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

即将推出的特性

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

贡献

1. Fork 存储库
2. 创建一个特性分支
3. 提交您的更改
4. 推送到您的分支
5. 创建一个 Pull Request

请确保您的 PR：

• 遵循现有的代码风格
• 包括适当的测试
• 根据需要更新文档
• 详细描述更改

依赖项

WhatsApp Web.js

该项目使用 whatsapp-web.js，这是一个非官方的 JavaScript 客户端库，用于通过 WhatsApp Web 浏览器应用程序连接 WhatsApp Web。 有关更多信息，请访问 whatsapp-web.js GitHub 存储库。

许可证

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。

日志记录

WhatsApp Web MCP 包含一个使用 Winston 构建的强大的日志记录系统。 日志记录系统提供：

• 多个日志级别（error、warn、info、http、debug）
• 带有彩色日志的控制台输出
• API 端点的 HTTP 请求/响应日志记录
• 结构化错误处理
• 环境感知日志级别（开发与生产）
• 在 MCP 命令模式下运行时，所有日志都定向到 stderr

日志级别

应用程序支持以下日志级别，按详细程度排序：

1. error - 阻止应用程序运行的严重错误
2. warn - 不会停止应用程序但需要注意的警告
3. info - 有关应用程序状态和事件的常规信息
4. http - HTTP 请求/响应日志记录
5. 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 运行时），记录器会自动调整其行为以适应测试环境。