MCP Whatsapp Web

MCP WhatsApp Web（TypeScript）

WhatsApp Web的模型上下文协议（MCP）服务器，用TypeScript实现。这个项目是原版的TypeScript移植 whatsapp mcp 存储库。

使用此MCP服务器，您可以：

• 搜索并阅读您的个人WhatsApp消息（包括媒体）
• 搜索您的联系人
• 向个人或团体发送消息
• 发送和接收媒体文件（图像、视频、文档、音频）

特性

• TypeScript实现：全类型代码库，提供更好的开发人员体验和代码可靠性
• WhatsApp Web集成：用途 whatsapp-web.js 用于直接连接到WhatsApp Web
• MCP服务器：实现 模型上下文协议 与AI助手无缝集成
• 媒体支持：发送和接收图像、视频、文档和音频消息
• 多种运输方式：支持stdio和SSE传输，实现灵活集成

建筑

此MCP服务器由以下部分组成：

1. TypeScript MCP服务器：实施模型上下文协议，为人工智能助手与WhatsApp交互提供标准化工具
2. WhatsApp网络服务：通过WhatsApp-Web.js连接到WhatsApp Web，处理身份验证，并管理消息发送/接收
3. 工具实施：为联系人、聊天、消息、媒体和身份验证提供各种工具

先决条件

• Node.js>=18.0.0
• npm或纱线
• Chrome/Chromium（Puppeteer用于WhatsApp网络连接）
• FFmpeg（可选，用于音频消息转换）

安装

手动安装

1. 克隆此存储库

   git clone https://github.com/mario-andreschak/mcp-whatsapp-web.git
   cd mcp-whatsapp-web

1. 安装依赖项

   npm install

1. 构建项目

   npm run build

1. 配置环境变量（可选）

复制示例环境文件并根据需要进行修改：

   cp .env.example .env

如果需要，您可以调整日志记录级别并指定FFmpeg的路径。

使用FLUJO进行安装

流动 提供了一个简化的安装过程：

1. 导航到FLUJO中的MCP部分
2. 点击“添加服务器”
3. 复制并粘贴此GitHub存储库URL： https://github.com/mario-andreschak/mcp-whatsapp-web
4. 点击“解析”、“克隆”、“安装”、“构建”和“更新服务器”

FLUJO将自动为您处理克隆、依赖项安装和构建过程。

用法

启动MCP服务器

npm start

默认情况下，这将使用stdio传输启动MCP服务器，这适用于与Claude Desktop或类似应用程序集成。

重要提示： 首次启动服务器后，您必须使用WhatsApp进行身份验证 get_qr_code 工具，并用手机扫描二维码。请参阅 认证 详细说明部分。

发展模式

npm run dev

这将以TypeScript监视模式启动处于开发模式的服务器，并自动重启服务器。

使用MCP检查器进行调试

npm run debug

这将启动MCP检查器工具，该工具提供了一个用于测试和调试MCP服务器的web界面。检查员允许您：

• 查看所有可用工具及其模式
• 直接执行工具并查看其响应
• 无需将服务器连接到AI助手即可测试服务器
• 调试工具执行并检查响应

连接到克劳德桌面

1. 为Claude Desktop创建配置文件：

   {
     "mcpServers": {
       "whatsapp": {
         "command": "node",
         "args": [
           "PATH_TO/dist/index.js"
         ]
       }
     }
   }

替换 PATH_TO 具有指向存储库的绝对路径。

1. 将此另存为 claude_desktop_config.json 在Claude Desktop配置目录中：

- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json - 窗户： %APPDATA%\Claude\claude_desktop_config.json - Linux： ~/.config/Claude/claude_desktop_config.json

1. 重新启动克劳德桌面

连接到游标

1. 为Cursor创建配置文件：

   {
     "mcpServers": {
       "whatsapp": {
         "command": "node",
         "args": [
           "PATH_TO/dist/index.js"
         ]
       }
     }
   }

替换 PATH_TO 具有指向存储库的绝对路径。

1. 将此另存为 mcp.json 在Cursor配置目录中：

- macOS/Linux： ~/.cursor/mcp.json - 窗户： %USERPROFILE%\.cursor\mcp.json

1. 重新启动游标

认证

第一次运行服务器时，您需要使用WhatsApp进行身份验证：

1. 启动MCP服务器
2. 重要提示： 您必须使用 get_qr_code 生成二维码的工具

- 在Claude或其他人工智能助手中，明确要求“使用get_qr_code工具对WhatsApp进行身份验证” - 助手将调用此工具并显示二维码图像

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

- 在手机上打开WhatsApp - 前往“设置”>“链接的设备”>“连接设备” - 将手机摄像头对准显示的二维码

您的会话将保存在本地 whatsapp-sessions 目录，并将在后续运行中自动重用。如果您不使用二维码进行身份验证，您将无法使用任何WhatsApp功能。

身份验证状态和注销

您可以检查当前的身份验证状态并管理会话：

• 使用 check_auth_status 用于验证您当前是否已通过身份验证的工具
• 如果您需要使用其他WhatsApp帐户进行身份验证或重新进行身份验证：

1. 使用 logout 退出当前会话的工具 1. 然后使用 get_qr_code 使用新二维码进行身份验证的工具

这在以下情况下特别有用：

• 您想在不同的WhatsApp帐户之间切换
• 您的会话已过期或无效
• 您遇到连接问题，需要重新进行身份验证

可用的MCP工具

认证

• get_qr_code-获取WhatsApp Web身份验证的二维码
• check_auth_status-检查您当前是否已通过WhatsApp的身份验证
• logout-退出WhatsApp并清除当前会话

联系人

• search_contacts-按姓名或电话号码搜索联系人
• get_contact-获取特定联系人的信息

聊天

• list_chats-列出带有元数据的可用聊天记录
• get_chat-获取特定聊天的信息
• get_direct_chat_by_contact-查找与特定联系人的直接聊天

消息

• list_messages-使用可选筛选器检索邮件
• get_message-按ID获取特定消息
• send_message-向聊天室发送短信

媒体

• send_file-将文件（图像、视频、文档）发送到聊天室
• send_audio_message-发送语音信息（语音备忘）
• download_media-从邮件中下载媒体

浏览器进程管理

此MCP服务器使用Puppeteer控制Chrome浏览器以实现WhatsApp Web连接。该服务器包括一个强大的浏览器进程管理系统，以防止孤立的Chrome进程。

自动浏览器清理

服务器自动执行以下操作：

• 使用PID跟踪系统跟踪Chrome浏览器进程
• 启动时清理孤立进程
• 关闭期间正确关闭浏览器进程
• 在中维护浏览器PID的记录 .chrome-pids.json

手动浏览器清理

如果你发现孤立的Chrome进程没有自动清理，你可以使用附带的清理实用程序：

npm run cleanup-browsers

此实用程序将：

1. 扫描可能与WhatsApp Web相关的Chrome进程
2. 显示潜在孤立进程的列表
3. 在终止之前要求确认
4. 清理PID跟踪文件

发展

项目结构

• src/index.ts-入口点
• src/server.ts-MCP服务器实现
• src/services/whatsapp.ts-WhatsApp网络服务
• src/tools/-各种WhatsApp功能的工具实现
• src/types/-TypeScript类型定义
• src/utils/-实用功能

脚本

• npm run build-构建TypeScript代码
• npm run dev-使用手表在开发模式下运行
• npm run lint-运行ESLint
• npm run format-使用Prettier格式化代码
• npm run cleanup-browsers-检测并清理孤立的Chrome浏览器进程

故障排除

身份验证问题

• 如果二维码没有出现，请尝试重新启动服务器
• 如果您已经通过身份验证，则不会显示二维码（使用 check_auth_status 验证）
• 如果需要重新验证，请使用 logout 先使用工具，然后请求新的二维码
• WhatsApp限制了链接设备的数量；您可能需要删除现有设备
• 如果您收到一条消息，说“当前没有可用的二维码”，但您已经通过身份验证，这是正常行为-使用 check_auth_status 确认您的身份验证状态

连接问题

• 确保您有稳定的互联网连接
• 如果连接失败，请尝试重新启动服务器
• 检查日志以了解详细的错误消息

浏览器进程问题

• 如果你注意到CPU使用率或内存消耗很高，可能会出现孤立的Chrome进程
• 跑 npm run cleanup-browsers 检测和清理孤立进程
• 如果服务器经常崩溃，请检查孤立进程并将其清理干净
• 在Windows上，您还可以使用任务管理器在命令行中查找多个带有“headless”的Chrome进程
• 在Linux/macOS上，使用 ps aux | grep chrome 检查孤立进程

许可证

麻省理工学院

______________________________________________________________________