网页-MCP

Name: 网页-MCP
Author: pnizer

作者：pnizer37 星标更新：2025-07-19

安装使用来源：spider==github.com

项目介绍

WhatsApp Web MCP

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

概览

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

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

免责声明

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

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

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

学习资源

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

安装

克隆仓库：

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

全局安装或直接使用npx：

# 全局安装
npm install -g .

# 或直接使用npx
npx .

使用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密钥进行认证。API密钥会在启动WhatsApp API服务器时自动生成，并显示在日志中：

WhatsApp API密钥：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配置

您可以创建一个webhook.json文件在您的认证数据目录（由--auth-data-path指定）中来接收传入的WhatsApp消息。

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": "联系人姓名",
  "message": "你好，世界！",
  "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客户端连接状态	无
`send_message`	向WhatsApp联系人发送消息	`number`：要发送到的电话号码<br>`message`：要发送的文本内容
`search_contacts`	按姓名或电话号码搜索联系人	`query`：用于查找联系人的搜索词
`get_messages`	从特定聊天中检索消息	`number`：要获取消息的电话号码<br>`limit`（可选）：要检索的消息数量
`get_chats`	获取所有WhatsApp聊天列表	无
`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
`send_media_message`	向WhatsApp联系人发送媒体消息	`number`：要发送到的电话号码<br>`source`：具有URI方案的媒体源（对于URL使用`http://`或`https://`，对于本地文件使用`file://`）<br>`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`：收件人<br>`message`：消息内容
`/api/send/media`	POST	发送媒体消息	`number`：收件人<br>`source`：具有URI方案的媒体源（对于URL使用`http://`或`https://`，对于本地文件使用`file://`）<br>`caption`（可选）：文本说明
`/api/messages/{messageId}/media/download`	POST	从消息下载媒体	无

群聊管理

端点	方法	描述	参数
`/api/groups`	GET	获取所有群聊	无
`/api/groups/search`	GET	搜索群聊	`query`：搜索词
`/api/groups/create`	POST	创建新群聊	`name`：群聊名称<br>`participants`：电话号码数组
`/api/groups/{groupId}`	GET	获取特定群聊的详细信息	无
`/api/groups/{groupId}/messages`	GET	获取来自群聊的消息	`limit`（查询参数）：消息数量
`/api/groups/{groupId}/participants/add`	POST	向群聊添加成员	`participants`：电话号码数组
`/api/groups/send`	POST	向群聊发送消息	`groupId`：群聊ID<br>`message`：消息内容

AI集成

Claude Desktop集成

选项1：使用NPX

启动WhatsApp API服务器：
```
npx wweb-mcp -m whatsapp-api -s local
```
使用您的WhatsApp移动应用扫描二维码

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

WhatsApp API密钥：1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

在您的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

在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

使用您的WhatsApp移动应用扫描二维码

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

WhatsApp API密钥：1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

在您的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"
            ]
        }
    }
}

重新启动Claude Desktop
WhatsApp功能将通过Claude的界面可用

架构

项目结构清晰地分离了关注点：

组件

WhatsAppService：与WhatsApp交互的核心业务逻辑
WhatsAppApiClient：连接到WhatsApp API的客户端
API Router：REST API路由
MCP Server：模型上下文协议实现

部署选项

WhatsApp API服务器：独立的REST API服务器
MCP服务器（独立）：直接连接到WhatsApp Web
MCP服务器（API客户端）：连接到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

代码检查和格式化

项目使用ESLint和Prettier进行代码质量和格式化：

# 运行代码检查器
npm run lint

# 自动修复代码检查问题
npm run lint:fix

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

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

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

发布

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

版本递增（patch，minor或major）
使用版本前缀为'v'的Git标签（例如，v0.2.1）
使用GitHub秘密发布到npm

要发布新版本：

转到GitHub存储库的操作标签
选择“发布包”工作流程
点击“运行工作流程”
选择版本递增类型（patch，minor或major）
点击“运行工作流程”以开始发布过程

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

故障排除

Claude Desktop集成问题

无法在Claude中以命令独立模式