WhatsApp MCP 服务器 (TypeScript/Baileys)

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

它允许你将个人 WhatsApp 账户连接到 AI 代理（如通过其桌面应用程序或 Cursor 连接的 Anthropic Claude），从而实现以下功能：

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

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

(可选：考虑添加一个类似于这里参考示例的截图或 GIF)

示例

用户：
向 WhatsApp 上的 "Meu amor" 发送一条消息说 "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"
}

工具结果：

Message sent successfully to 5599xxxxxx@s.whatsapp.net (ID: XXXXXXXXXXX).

主要功能 (MCP 工具)

服务器向连接的 AI 代理提供了以下工具：

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

安装

前提条件

• 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": 15, // 可选：根据需要调整启动超时时间
         "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 服务器，该服务器通过标准输入输出（stdio）监听来自 AI 客户端的请求。
4. 提供查询本地 SQLite 数据库或使用 Baileys 套接字发送消息的 MCP 工具。
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 (>= v23.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 文档。

致谢

• https://github.com/lharries/whatsapp-mcp 该项目与本代码库类似，但使用了 Go 和 Python 语言。

许可证

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