WhatsApp Web MCP

一个强大的桥梁，通过模型上下文协议（MCP）连接WhatsApp Web和AI模型。该项目使像Claude这样的AI模型能够通过标准化接口与WhatsApp交互，从而轻松地以编程方式自动化和增强WhatsApp的交互。

概览

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

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

免责声明

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

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

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

安装

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 服务器重启之间保持不变。

认证方法

本地认证（推荐）

• 仅需扫描一次二维码
• 凭证在会话之间保持
• 长期运行更稳定

无认证

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

使用

运行模式

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 服务器: Model Context Protocol 实现

部署选项

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 最佳实践，并在整个项目中保持一致的代码风格。

故障排除

Claude Desktop 集成问题

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

即将推出的功能

• 为接收消息和其他 WhatsApp 事件创建 Webhook
• 支持发送媒体文件（图片、音频、文档）
• 群聊管理功能
• 联系人管理（添加/移除联系人）
• 常见场景的消息模板
• 增强的错误处理和恢复

贡献指南

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

请确保您的 PR：

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

依赖项

WhatsApp Web.js

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

许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

日志记录

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

• 多个日志级别（error, warn, info, http, debug）
• 控制台输出带有彩色日志
• API 端点的 HTTP 请求/响应日志
• 结构化的错误处理
• 环境感知的日志级别（开发环境 vs 生产环境）
• 在 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 一起运行时），日志记录器会自动调整其行为以适应测试环境。