STARWARCLOUD STARWAR.AI
返回市场
WhatsApp-MCP-类型脚本

WhatsApp-MCP-类型脚本

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

项目介绍

WhatsApp MCP 服务器 (TypeScript/Baileys)

smithery 徽章

这是一个用于 WhatsApp 的模型上下文协议 (MCP) 服务器，使用 TypeScript 构建，并使用了 @whiskeysockets/baileys 库。

它允许您将自己的个人 WhatsApp 账户连接到一个 AI 代理（如通过桌面应用或 Cursor 连接的 Anthropic Claude），使其能够：

  • 搜索您的个人 WhatsApp 消息。
  • 搜索您的联系人（个人，而不是群组）。
  • 列出最近的聊天记录。
  • 获取特定聊天的消息历史。
  • 向个人或群组发送消息。

它直接使用 WhatsApp Web 多设备 API 连接到您的个人 WhatsApp 账户。所有消息和认证详情都存储在本地的 SQLite 数据库 (./data/) 和认证缓存 (./auth_info/) 中。数据仅在 AI 代理明确使用提供的 MCP 工具时才会发送（您可以通过代理界面控制这些工具）。

(可选：考虑添加类似参考示例的截图或 GIF)

示例

用户： 向“Meu amor”发送一条 WhatsApp 消息说“Te amo”

助手： 好的，我需要先找到这个联系人。 使用工具：whatsapp.search_contacts

{
  "query": "Meu amor"
}

工具结果：

[
  {
    "jid": "5599xxxxxx@s.whatsapp.net",
    "name": "Meu Amor"
  }
]

助手： 找到了联系人。现在发送消息。 使用工具：whatsapp.send_message

{
  "recipient": "5599xxxxxx@s.whatsapp.net",
  "message": "Te amo"
}

工具结果：

消息已成功发送给 5599xxxxxx@s.whatsapp.net (ID: XXXXXXXXXXX)。

主要功能 (MCP 工具)

该服务器向连接的 AI 代理暴露以下工具：

  • search_contacts: 根据姓名或电话号码部分（JID）搜索联系人。
  • list_messages: 获取特定聊天的消息历史，支持分页。
  • list_chats: 列出您的聊天记录，按活动或名称排序，支持过滤和分页，可选地包括最后一条消息的详细信息。
  • get_chat: 获取特定聊天的详细信息。
  • get_message_context: 获取特定消息 ID 前后发送的消息以提供上下文。
  • send_message: 向指定的接收者 JID（用户或群组）发送文本消息。

安装

通过 Smithery 安装

要通过 Smithery 自动安装 WhatsApp MCP 服务器：

npx -y @smithery/cli install @jlucaso1/whatsapp-mcp-ts --client claude

先决条件

  • Node.js: 版本 23.10.0 或更高（如 package.json 所指定）。您可以使用 node -v 检查版本。（初始支持 TypeScript 和 SQLite）
  • npm（或 yarn/pnpm）：通常随 Node.js 一起提供。
  • AI 客户端: Anthropic Claude 桌面应用、Cursor、Cline 或 Roo Code（或其他兼容 MCP 的客户端）。

步骤

  1. 克隆此仓库：

    git clone <your-repo-url> whatsapp-mcp-ts
cd whatsapp-mcp-ts

  2. 安装依赖项：

    npm install
# 或 yarn install / pnpm install

  3. 首次运行服务器： 使用 node 直接运行主脚本。

    node src/main.ts
    • 第一次运行时，它可能会生成一个使用 quickchart.io 的二维码链接，并尝试在默认浏览器中打开。
    • 使用您的 WhatsApp 移动应用扫描此二维码（设置 > 链接设备 > 链接设备）。
    • 认证凭据将保存在本地的 auth_info/ 目录中（此目录被 git 忽略）。
    • 消息开始同步并存储在 ./data/whatsapp.db。这可能需要一些时间，具体取决于您的历史记录大小。检查 wa-logs.txt 和控制台输出以了解进度。
    • 保持此终端窗口运行。同步完成后可以关闭。

AI 客户端配置

您需要告诉您的 AI 客户端如何启动此 MCP 服务器。

  1. 准备配置 JSON： 复制以下 JSON 结构。您需要将 {{PATH_TO_REPO}} 替换为克隆此仓库的目录的绝对路径。

    {
  "mcpServers": {
    "whatsapp": {
      "command": "node",
      "args": [
        "{{PATH_TO_REPO}}/src/main.ts"
      ],
      "timeout": 1.5, // 可选：如有必要调整启动超时时间
      "disabled": false
    }
  }
}
    • 获取绝对路径： 在终端中导航到 whatsapp-mcp-ts 目录并运行 pwd。使用此输出作为 {{PATH_TO_REPO}}。

  2. 保存配置文件：

    • 对于 Claude Desktop: 将 JSON 保存为 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（可能的路径，如有必要验证）
    • 对于 Cursor: 将 JSON 保存为 mcp.json 在其配置目录中：
      • ~/.cursor/mcp.json

  3. 重启 Claude Desktop / Cursor： 关闭并重新打开您的 AI 客户端。它应该现在检测到“whatsapp”MCP 服务器并允许您使用其工具。

使用方法

一旦服务器运行（无论是通过手动运行 node src/main.ts 还是通过配置文件由 AI 客户端启动）并连接到您的 AI 客户端，您可以通过代理的聊天界面与您的 WhatsApp 数据进行交互。请求它搜索联系人、列出最近的聊天记录、阅读消息或发送消息。

架构概述

此应用程序是一个单一的 Node.js 进程，它：

  1. 使用 @whiskeysockets/baileys 连接到 WhatsApp Web API，处理身份验证和实时事件。
  2. 使用 node:sqlite 将 WhatsApp 聊天和消息本地存储在 SQLite 数据库 (./data/whatsapp.db) 中。
  3. 使用 @modelcontextprotocol/sdk 运行一个 MCP 服务器，监听来自 AI 客户端的标准输入/输出（stdio）请求。
  4. 提供 MCP 工具，查询本地 SQLite 数据库或使用 Baileys 套接字发送消息。
  5. 使用 pino 进行日志记录（wa-logs.txt 用于 WhatsApp 事件，mcp-logs.txt 用于 MCP 服务器活动）。

数据存储与隐私

  • 认证: 您的 WhatsApp 连接凭据存储在本地的 ./auth_info/ 目录中。
  • 消息与聊天: 您的消息历史和聊天元数据存储在本地的 ./data/whatsapp.db SQLite 文件中。
  • 本地数据: auth_info/ 和 data/ 都包含在 .gitignore 中，以防意外提交。请将这些目录视为敏感信息。
  • LLM 交互: 数据仅在 AI 代理积极使用提供的 MCP 工具之一（例如 list_messages，send_message）时才发送给连接的大规模语言模型 (LLM)。服务器本身不会主动将您的数据发送到其他地方。

技术细节

  • 语言: TypeScript
  • 运行时: Node.js (>= v2.3.10.0)
  • WhatsApp API: @whiskeysockets/baileys
  • MCP SDK: @modelcontextprotocol/sdk
  • 数据库: node:sqlite（捆绑的 SQLite）
  • 日志记录: pino
  • 模式验证: zod（用于 MCP 工具输入）

故障排除

  • 二维码问题：
    • 如果二维码链接没有自动打开，请检查控制台输出中的 quickchart.io URL 并手动打开。
    • 确保您及时使用手机上的 WhatsApp 应用扫描二维码。
  • 认证失败 / 登出：
    • 如果连接因 DisconnectReason.loggedOut 错误而关闭，您需要重新认证。停止服务器，删除 ./auth_info/ 目录，然后重新启动服务器 (node src/main.ts) 以获取新的二维码。
  • 消息同步问题：
    • 初始同步可能需要时间。检查 wa-logs.txt 以了解活动情况。
    • 如果消息似乎不同步或丢失，您可能需要完全重置。停止服务器，删除 ./auth_info/ 和 ./data/ 目录，然后重新启动服务器以重新认证和重新同步历史记录。
  • MCP 连接问题（Claude/Cursor）：
    • 再次检查 claude_desktop_config.json 或 mcp.json 中的 command 和 args（特别是 {{PATH_TO_REPO}}）。确保路径是绝对且正确的。
    • 验证 Node.js 是否正确安装并在系统 PATH 中。
    • 检查 AI 客户端的日志以查找启动 MCP 服务器的相关错误。
    • 检查此服务器的日志 (mcp-logs.txt) 以查找 MCP 相关的错误。
  • 发送消息时出现错误：
    • 确保接收者的 JID 是正确的（例如，用户为 number@s.whatsapp.net，群组为 groupid@g.us）。
    • 检查 wa-logs.txt 以获取来自 Baileys 的具体错误。
  • 一般问题： 检查 wa-logs.txt 和 mcp-logs.txt 以获取详细的错误消息。

对于进一步的 MCP 集成问题，请参阅 官方 MCP 文档。

致谢

许可

本项目根据 ISC 许可证授权（参见 package.json）。