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 或命令模式提供灵活的部署选项
• 支持直接的 WhatsApp 客户端集成和基于 API 的连接

免责声明

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

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

本项目与 WhatsApp 及其任何子公司或关联公司无关，也未得到它们的认可。官方的 WhatsApp 网站可以在 whatsapp.com 找到。“WhatsApp”以及相关名称、标志、徽标和图像是各自所有者的注册商标。此外，不能保证使用此方法不会被封禁。WhatsApp 不允许在其平台上使用机器人或非官方客户端，因此不应认为这种方法是完全安全的。

学习资源

要了解如何在实际场景中使用 WhatsApp Web MCP，请查看以下文章：

• 将 WhatsApp 与 AI 集成：设置 WhatsApp MCP 服务器指南
• 将 OpenAI 代理 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
   

配置

命令行选项

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
  }
}

配置选项

Webhook负载

当接收到消息并通过过滤器后，将向配置的URL发送带有以下JSON负载的POST请求：

{
  "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

可用工具

可用资源

REST API 端点

联系人与消息

群组管理

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 路由器: REST API 的 Express 路由
4. MCP 服务器: 模型上下文协议实现

部署选项

1. WhatsApp API 服务器: 独立的 REST API 服务器
2. MCP 服务器（独立）: 直接连接到 WhatsApp Web
3. 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。工作流处理：

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 桌面集成问题

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

功能

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

即将推出的功能

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

贡献

1. 分叉仓库
2. 创建功能分支
3. 提交你的更改
4. 推送到你的分支
5. 创建 Pull Request

请确保您的 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

日志级别

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

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