WhatsApp Web MCP

WhatsApp网络MCP


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

概述

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

• 通过模型上下文协议（MCP）创建标准化接口
• 提供MCP服务器访问WhatsApp功能
• 通过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

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

   # Install globally
   npm install -g .

   # Or use with npx directly
   npx .

1. 使用Docker构建：

   docker build . -t wweb-mcp:latest

配置

命令行选项

API密钥验证

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

WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

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

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 配置

您可以通过创建一个 webhook.json 身份验证数据目录中的文件（由指定 --auth-data-path).

网钩 JSON 格式

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

配置选项

Webhook 有效载荷

当收到消息并通过过滤器时，POST请求将发送到配置的URL，并包含以下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

可用工具

source：具有URI方案的媒体源（使用 http:// 或 https:// 对于URL， file:// 对于本地文件） caption （可选）：媒体文字说明|

可用资源

REST API端点

联系人和消息

source：具有URI方案的媒体源（使用 http:// 或 https:// 对于URL， file:// 对于本地文件） caption （可选）：文本标题| | /api/messages/{messageId}/media/download |POST |从消息中下载媒体|无|

组管理

人工智能集成

Claude桌面集成

选项1：使用NPX

1. 启动WhatsApp API服务器：

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

1. 使用WhatsApp移动应用程序扫描二维码

1. 请注意日志中显示的API密钥：

   WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

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

1. 使用WhatsApp移动应用程序扫描二维码

1. 请注意日志中显示的API密钥：

   WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

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

1. 重新启动克劳德桌面

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

建筑

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

组件

1. WhatsAppService：与WhatsApp交互的核心业务逻辑
2. WhatsAppApiClient：用于连接到WhatsApp API的客户端
3. API路由器：REST API的快速路由
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

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

出版

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

1. 版本递增(patch, minor，或 major)
2. Git标签，版本前缀为“v”（例如v0.2.1）
3. 使用GitHub secrets发布到npm

要发布新版本，请执行以下操作：

1. 转到GitHub存储库操作选项卡
2. 选择“发布包”工作流
3. 点击“运行工作流”
4. 选择版本增量类型（补丁、次要或主要）
5. 点击“运行工作流”开始发布过程

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

故障排除

Claude桌面集成问题

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

特性

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

即将推出的功能

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

贡献

1. 分叉存储库
2. 创建要素分支
3. 提交您的更改
4. 推到您的分支
5. 创建拉取请求

请确保您的PR：

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

依赖项

WhatsApp Web.js

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

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

日志记录

WhatsApp Web MCP包括一个用Winston构建的强大日志系统。测井系统提供：

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

日志级别

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

1. 错误 -阻止应用程序运行的关键错误
2. 警告 -不会停止应用程序但需要注意的警告
3. 信息 -有关应用程序状态和事件的一般信息
4. 超文本传输协议 -HTTP请求/响应日志记录
5. 调试 -详细的调试信息

配置日志级别

您可以在启动应用程序时使用配置日志级别 --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运行时），记录器会自动调整其行为以适合测试环境。