WhatsApp MCP 服务器 (TypeScript/Baileys)

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

它允许您将您的个人 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

工具结果：

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

工具结果：

主要功能（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 # or 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, // Optional: Adjust startup timeout if needed "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 工具输入）

故障排除

• QR码问题：
  • 如果二维码链接没有自动打开，请检查控制台输出中的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 ）。