WhatsApp Web MCP

WhatsApp Web MCP

一个通过 Model Context Protocol（MCP）将 WhatsApp Web 与 AI 模型连接起来的 Node.js 应用。本项目提供了与 WhatsApp 进行程序化交互的标准化接口，可通过 AI 驱动的工作流实现自动消息发送、联系人管理和群聊功能。

概述

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

• 通过 Model Context Protocol（MCP）创建标准化接口
• 提供对 WhatsApp 功能的 MCP 服务访问
• 通过 SSE 或 Command 模式提供灵活的部署选项
• 同时支持直接集成 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 使用：

   # Install globally
   npm install -g .
   
   # Or use with npx directly
   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 文件，以配置用于接收传入 WhatsApp 消息的 webhook。

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	字符串（可选）	在 Authorization 标头中作为 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：群组的 ID participants：要添加的电话号码数组
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	GET	获取 WhatsApp 连接状态	无
/api/contacts	GET	获取所有联系人	无
/api/contacts/search	GET	搜索联系人	query：搜索词
/api/chats	GET	获取所有聊天	无
/api/messages/{number}	GET	获取聊天中的消息	limit（查询）：消息数量
/api/send	POST	发送消息	number：收件人 message：消息内容
/api/send/media	POST	发送媒体消息	number：收件人 source：带 URI 方案的媒体来源（URL 使用 http:// 或 https://，本地文件使用 file://） caption（可选）：文字说明
/api/messages/{messageId}/media/download	POST	下载消息中的媒体	无

群组管理

端点	方法	描述	参数
/api/groups	GET	获取所有群组	无
/api/groups/search	GET	搜索群组	query：搜索词
/api/groups/create	POST	创建新群组	name：群组名称 participants：号码数组
/api/groups/{groupId}	GET	获取特定群组的详细信息	无
/api/groups/{groupId}/messages	GET	获取群组中的消息	limit（查询）：消息数量
/api/groups/{groupId}/participants/add	POST	向群组添加成员	participants：号码数组
/api/groups/send	POST	向群组发送消息	groupId：群组 ID 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. 即可通过 Claude 界面使用 WhatsApp 功能

架构

项目采用清晰的关注点分离结构：

组件

1. WhatsAppService：与 WhatsApp 交互的核心业务逻辑
2. WhatsAppApiClient：用于连接 WhatsApp API 的客户端
3. API Router：REST API 的 Express 路由
4. MCP Server：Model Context Protocol 实现

部署选项

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 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。此工作流会处理：

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 运行时），日志记录器会自动调整行为，以适用于测试环境。