mcp-whatsapp-web

MCP WhatsApp 网页版 (TypeScript)

一个用于 WhatsApp Web 的模型上下文协议 (MCP) 服务器，使用 TypeScript 实现。该项目是原始whatsapp-mcp代码库的 TypeScript 移植版本。

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

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

特征

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

建筑学

该 MCP 服务器包括：

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

先决条件

• Node.js >= 18.0.0
• npm 或 yarn
• Chrome/Chromium（Puppeteer 用于 WhatsApp 网络连接）
• 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 服务器

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

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

开发模式

这将以 TypeScript 监视模式在开发模式下启动服务器并自动重启服务器。

使用 MCP Inspector 进行调试

这将启动 MCP 检查器工具，该工具提供了一个用于测试和调试 MCP 服务器的 Web 界面。检查器允许您执行以下操作：

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

连接到 Claude Desktop

1. 为Claude Desktop创建配置文件：
   { "mcpServers": { "whatsapp": { "command": "node", "args": [ "PATH_TO/dist/index.js" ] } } }
   将PATH_TO替换为存储库的绝对路径。
2. 将其保存为 Claude Desktop 配置目录中的claude_desktop_config.json ：
   • 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桌面

连接到光标

1. 为Cursor创建配置文件：
   { "mcpServers": { "whatsapp": { "command": "node", "args": [ "PATH_TO/dist/index.js" ] } } }
   将PATH_TO替换为存储库的绝对路径。
2. 将其保存为 Cursor 配置目录中的mcp.json ：
   • macOS/Linux： ~/.cursor/mcp.json
   • Windows： %USERPROFILE%\.cursor\mcp.json
3. 重启光标

验证

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

1. 启动 MCP 服务器
2. **重要提示：**您必须使用get_qr_code工具来生成二维码
   • 在 Claude 或其他 AI 助手中，明确要求“使用 get_qr_code 工具验证 WhatsApp”
   • 助手将调用此工具并显示二维码图像
3. 使用 WhatsApp 移动应用扫描二维码
   • 在手机上打开 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 网页连接。该服务器包含一个强大的浏览器进程管理系统，以防止出现孤立的 Chrome 进程。

自动浏览器清理

服务器自动：

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

手动浏览器清理

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

此实用程序将：

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检查孤立进程

执照

麻省理工学院

该项目是lharries的原始whatsapp-mcp的 TypeScript 端口。