MCP WhatsApp Web (TypeScript)

一个用 TypeScript 实现的适用于 WhatsApp Web 的 Model Context Protocol (MCP) 服务器。这个项目是原始 whatsapp-mcp 仓库的 TypeScript 版本。

通过这个 MCP 服务器，您可以：

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

功能

• TypeScript 实现：完全类型化的代码库，提供更好的开发体验和代码可靠性
• WhatsApp Web 集成：使用 whatsapp-web.js 直接连接到 WhatsApp Web
• MCP 服务器：实现 Model Context Protocol 以无缝集成 AI 助手
• 媒体支持：发送和接收图片、视频、文档和音频消息
• 多种传输选项：支持 stdio 和 SSE 传输，以便灵活集成

架构

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

1. TypeScript MCP 服务器：实现 Model Context Protocol 以提供标准化工具，供 AI 助手与 WhatsApp 交互
2. WhatsApp Web 服务：通过 whatsapp-web.js 连接到 WhatsApp Web，处理身份验证并管理消息发送/接收
3. 工具实现：提供各种工具用于联系人、聊天、消息、媒体和身份验证

前提条件

• Node.js >= 18.0.0
• npm 或 yarn
• Chrome/Chromium（Puppeteer 用于连接 WhatsApp Web 时使用）
• FFmpeg（可选，用于音频消息转换）

安装

手动安装

1. 克隆此仓库

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

2. 安装依赖项

   npm install
   

3. 构建项目

   npm run build
   

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

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

   cp .env.example .env
   

   您可以调整日志级别，并在需要时指定 FFmpeg 路径。

使用 FLUJO 安装

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 或类似应用程序集成。

重要： 首次启动服务器后，您必须使用 get_qr_code 工具并通过手机扫描二维码来完成 WhatsApp 的身份验证。请参阅 身份验证 部分以获取详细说明。

开发模式

npm run dev

这将以 TypeScript 监视模式和自动重启服务器的方式启动开发模式的服务器。

使用 MCP Inspector 调试

npm run debug

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

• 查看所有可用工具及其架构
• 直接执行工具并查看其响应
• 在不连接到 AI 助手的情况下测试您的服务器
• 调试工具执行并检查响应

连接到 Claude Desktop

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

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

   将 PATH_TO 替换为仓库的绝对路径。

2. 将此文件保存为 claude_desktop_config.json 到您的 Claude Desktop 配置目录中：

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

3. 重新启动 Claude Desktop

连接到 Cursor

1. 为 Cursor 创建一个配置文件：

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

   将 PATH_TO 替换为仓库的绝对路径。

2. 将此文件保存为 mcp.json 到您的 Cursor 配置目录中：

   • macOS/Linux: ~/.cursor/mcp.json
   • Windows: %USERPROFILE%\.cursor\mcp.json

3. 重新启动 Cursor

身份验证

首次运行服务器时，您需要与 WhatsApp 进行身份验证：

1. 启动 MCP 服务器
2. 重要： 您必须使用 get_qr_code 工具生成二维码
   • 在 Claude 或其他 AI 助手中，明确要求“使用 get_qr_code 工具进行 WhatsApp 身份验证”
   • 助手将调用此工具并显示二维码图像
3. 使用您的 WhatsApp 手机应用程序扫描二维码
   • 在手机上打开 WhatsApp
   • 前往设置 > 链接设备 > 链接设备
   • 将手机摄像头对准显示的二维码

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

身份验证状态和注销

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

• 使用 check_auth_status 工具验证您当前是否已认证
• 如果您需要使用不同的 WhatsApp 账号进行认证或重新认证：
  1. 使用 logout 工具从当前会话中登出
  2. 然后使用 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 浏览器进程
• 在启动时清理孤立进程
• 在关闭时正确关闭浏览器进程
• 在 .chrome-pids.json 中维护浏览器 PID 的记录

手动浏览器清理

如果您注意到未被自动清理的孤立 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 Web 服务
• 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 来检查孤立的进程

许可证

MIT

此项目是 lharries 的原始 whatsapp-mcp 的 TypeScript 版本。