STARWARCLOUD STARWAR.AI
返回市场
麦克佩斯-WhatsApp-Web

麦克佩斯-WhatsApp-Web

作者：mario-andreschak13 星标更新：2025-04-30
安装使用来源：spider==github.com

项目介绍

MCP WhatsApp Web (TypeScript)

这是一个使用TypeScript实现的用于WhatsApp Web的模型上下文协议（MCP）服务器。该项目是原始whatsapp-mcp仓库的TypeScript版本。

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

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

image image

特性

  • 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 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工具，它提供了一个Web界面，用于测试和调试您的MCP服务器。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版本。