AI导哈

WhatsApp消息管理服务器

一个基于TypeScript和Baileys库构建的WhatsApp MCP服务器，允许将个人WhatsApp账户连接到AI代理，实现消息搜索、联系人管理、聊天记录检索和消息发送功能。

  • by Joshnaacsha
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 joshnaacsha/mcp-shipathon

使用说明

WhatsApp MCP服务器（Types/Baileys）

这是WhatsApp的模型上下文协议（MCP）服务器，使用TypeScript构建，并使用 @whiskeysockets/baileys 图书馆。

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

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

它直接连接到您的 个人WhatsApp帐户 使用WhatsApp Web多设备API。您的所有消息和身份验证详细信息都已存储 本地 在SQLite数据库中(./data/)以及身份验证缓存(./auth_info/).只有当连接的AI代理明确使用提供的MCP工具（您通过代理的接口控制）时，数据才会发送到它。

（可选：考虑添加类似于此处参考示例的屏幕截图或GIF）

示例

用户： 在whatsapp中向“Meu amo”发送一条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"
}

工具结果：

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（用户或组）发送短信。

安装

通过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 Desktop应用程序、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. 保存配置文件：

    • 对于 克劳德桌面： 将JSON另存为 claude_desktop_config.json 在其配置目录中：
      • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
      • 窗户： %APPDATA%\Claude\claude_desktop_config.json （可能的路径，如果需要，请验证）
      • Linux： ~/.config/Claude/claude_desktop_config.json （可能的路径，如果需要，请验证）
    • 对于 光标： 将JSON另存为 mcp.json 在其配置目录中：
      • ~/.cursor/mcp.json

  3. 重新启动克劳德桌面/光标： 关闭并重新打开AI客户端。它现在应该可以检测到“whatsapp”MCP服务器，并允许您使用其工具。

用法

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

架构概述

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

  1. 用途 @whiskeysockets/baileys 连接到WhatsApp Web API，处理身份验证和实时事件。
  2. 将WhatsApp聊天记录和消息本地存储在SQLite数据库中(./data/whatsapp.db)使用 node:sqlite.
  3. 使用以下命令运行MCP服务器 @modelcontextprotocol/sdk 它通过标准输入/输出（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).服务器本身不会主动将您的数据发送到其他任何地方。

技术细节

  • 语言： 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）：
    • 仔细检查 command 和 args （尤其是 {{PATH_TO_REPO}})在你的 claude_desktop_config.json 或 mcp.json。确保路径绝对正确。
    • 验证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).

相关 MCP