AI导哈

WhatsApp自动化服务器

一个生产就绪的WhatsApp自动化服务器，通过MCP协议连接Claude或其他兼容客户端，实现消息发送、群组管理、媒体传输等全面WhatsApp自动化功能。

  • by NIXKnight
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 NIXKnight/WhatsApp-MCP

使用说明

WhatsApp MCP服务器

一个生产就绪的模型上下文协议（MCP）服务器，使用以下方式将Claude（或任何兼容MCP的客户端）连接到WhatsApp 百利甜酒。此服务器通过二维码身份验证链接的个人WhatsApp帐户运行WhatsApp。

特性

WhatsApp MCP服务器提供了12个工具，以实现WhatsApp的完全自动化：

  1. send_message --向个人联系人发送纯文本消息，可选择提及和引用/回复支持
  2. 获取消息 --从聊天中检索最新消息
  3. list_contacts --返回所有已知的WhatsApp联系人
  4. get_contact --通过JID获取单个联系人的元数据
  5. list_groups --返回您所属的所有WhatsApp群组
  6. get_group --获取完整的组元数据，包括参与者列表和管理员角色
  7. send_group_message --向群组发送带有可选提及和引用/回复支持的消息
  8. send_media --向联系人或组发送媒体文件（图像、视频、音频、文档）
  9. 下载_媒体 --从收到的邮件中下载媒体附件
  10. check_new_消息 --轻量级轮询，用于检查自给定时间戳以来的新消息
  11. get_unread_chats --返回所有包含未读消息的聊天记录，包括JID、姓名、未读计数和最新未读消息
  12. 获取_读取_消息 --从特定聊天中获取未读消息

技术栈

  • Node.js v20+
  • TypeScript --类型安全实施
  • 百利v7 --反向工程WhatsApp Web客户端
  • MCP TypeScript SDK --模型上下文协议实现
  • 皮诺 --结构化日志记录到stderr
  • qrcode终端 --终端二维码渲染

项目结构

WhatsApp-MCP/
├── src/
│   ├── index.ts                 # MCP server entrypoint
│   ├── whatsapp.ts              # Baileys socket management & custom store
│   ├── store.ts                 # In-memory message/contact/chat store
│   ├── login.ts                 # QR code login utility
│   └── tools/
│       ├── messages.ts          # send_message, get_messages tools
│       ├── contacts.ts          # list_contacts, get_contact tools
│       ├── groups.ts            # list_groups, get_group, send_group_message tools
│       └── media.ts             # send_media, download_media tools
├── dist/                        # Compiled JavaScript (after build)
├── ~/.whatsapp-mcp/             # Persisted authentication credentials and store data (gitignored)
├── package.json
├── tsconfig.json
└── .gitignore

先决条件

  • Node.js v20或更高版本 --确保安装了兼容的版本
  • WhatsApp帐户 --使用主要或次要号码；请注意WhatsApp服务条款
  • 安装了WhatsApp的手机 --二维码链接所需（链接设备功能）

安装

克隆存储库并安装依赖项：

git clone https://github.com/yourusername/WhatsApp-MCP.git
cd WhatsApp-MCP
npm install
npm run build

认证

在服务器可以发送和接收消息之前，您必须通过二维码验证您的WhatsApp帐户。

首次登录

运行登录实用程序扫描二维码：

npm run login

该工具将：

  1. 在您的终端中生成二维码
  2. 通过WhatsApp>设置>链接设备>链接设备提示您用手机扫描
  3. 将凭据保存到 ~/.whatsapp-mcp/auth_info/ （忽略）
  4. 身份验证完成后退出

凭据保留在 ~/.whatsapp-mcp/auth_info/ 目录，并在后续服务器启动时重用。你只需要运行一次。

重新认证

如果您看到“已注销”消息或需要重新验证：

rm -rf ~/.whatsapp-mcp/auth_info/
npm run login

配置

克劳德桌面版

要将此服务器与Claude Desktop一起使用，请将其添加到您的Claude配置文件中。

  1. 打开 ~/.claude/claude_desktop_config.json （若缺失，则创建）
  2. 添加服务器条目：
{
  "mcpServers": {
    "whatsapp": {
      "command": "node",
      "args": ["/full/path/to/WhatsApp-MCP/dist/index.js"]
    }
  }
}

替换 /full/path/to/WhatsApp-MCP 与你的项目的绝对路径。

  1. 重新启动克劳德桌面
  2. 验证服务器是否出现在Claude的“工具”或“MCP”部分

克劳德代码

要与Claude Code一起使用：

cd /path/to/WhatsApp-MCP
claude mcp add whatsapp "npm run start"

或在中手动配置 ~/.claude/claude_code_config.json:

{
  "mcpServers": {
    "whatsapp": {
      "command": "npm",
      "args": ["run", "start"],
      "cwd": "/full/path/to/WhatsApp-MCP"
    }
  }
}

用法

一旦连接到Claude或Claude Code，您就可以使用自然语言与WhatsApp进行交互。

消息示例

发送短信：

Send a WhatsApp message to 923001234567 saying "Hello, how are you?"

列出您的组：

Show me all my WhatsApp groups

获取最新消息：

Get the last 10 messages from group 120363039783372408@g.us

发送一条提及的消息：

Send a message to group 120363039783372408@g.us saying "Hey @923338894615, check this out!" and mention 923338894615@s.whatsapp.net

发送媒体文件：

Send the image at /home/user/photo.jpg to 923001234567 with caption "Check this out!"

下载媒体：

Download the media from message 3AEBEEF123ABC456 in chat 923001234567@s.whatsapp.net

获取组详细信息：

Fetch metadata for group 120363039783372408@g.us including participant list

发送语音备忘：

Send a voice note from /home/user/recording.ogg to 923001234567 with ptt enabled

查看未读聊天记录：

Show me all my unread chats with message counts

从聊天中获取未读消息：

Get unread messages from chat 923001234567@s.whatsapp.net

工具参考

工具 参数 返回
send_message to （电话）， text, mentions?, quotedMessageId?, quotedParticipant? 确认或错误
get_messages jid （聊天ID）， limit? （默认值20） 消息对象数组
list_contacts （无） 联系人对象数组
get_contact jid （联系JID） 单个联系对象或错误
list_groups （无） 组对象数组
get_group jid （组JID） 包含参与者的完整组元数据
send_group_message jid （组）， text, mentions?, quotedMessageId?, quotedParticipant? 确认或错误
send_media to （电话/JID）， filePath, caption?, mediaType? （自动检测）， ptt? （按键通话以获取语音备忘） 确认或错误
download_media messageId, jid, outputDir? （默认值./downloads） 磁盘上的文件路径或错误
check_new_messages since? （时间戳单位为毫秒，默认值为0） 新消息对象数组
get_unread_chats （none） 包含JID、姓名、未读计数和最新未读消息的未读聊天对象数组
get_unread_messages jid （聊天ID） 聊天中未读消息对象的数组

关键实施细节

自定义内存存储

Baileys v7已删除 makeInMemoryStore()。此服务器实现了一个最小的自定义存储，该存储：

  • 在内存中跟踪聊天记录、联系人和消息历史记录
  • 绑定到Baileys套接字事件以实现自动同步
  • 在中提供辅助函数 store.ts 用于查询数据
  • 将存储数据序列化为 ~/.whatsapp-mcp/store_data.json 用于跨重启的持久性

注： 该商店坚持 ~/.whatsapp-mcp/store_data.json 并在重启后幸存下来。从WhatsApp服务器重新连接后，历史消息会逐渐同步。

二维码渲染

Baileys v7已弃用 printQRInTerminal()。此服务器：

  • 使用 qrcode-terminal 用于生成ASCII二维码的软件包
  • 将二维码写入 标准错误 （非stdout）以保留stdout上的MCP JSON-RPC流量
  • 在连接过程中检测QR事件并自动呈现

身份验证和版本控制

  • 用途 fetchLatestBaileysVersion() 检索最新的WhatsApp Web协议版本
  • 实现 makeCacheableSignalKeyStore() 用于可靠的密钥管理
  • 存储在中的多文件身份验证状态 ~/.whatsapp-mcp/auth_info/

提及和引用

小组讨论：

对于LID寻址组（现代组格式），通过以下方式发送提及 contextInfo.mentionedJid:

const contextInfo = {
  mentionedJid: ['923338894615@s.whatsapp.net', '923001234567@s.whatsapp.net']
};

包含 @number 在每个提到的用户的消息文本中。

引用/回复：

引号使用三个contextInfo字段：

const contextInfo = {
  stanzaId: messageId,              // ID of message being quoted
  participant: senderJid,            // JID of message sender (or LID in groups)
  quotedMessage: messageObject       // The quoted message content
};

如果消息不在本地存储中，您可以提供 quotedParticipant 明确地。

日志记录

所有诊断输出（连接事件、错误、警告）都写入 标准错误 （文件描述符2）。 Stdout专用于MCP JSON-RPC通信 以避免协议损坏。

记录器使用最小配置的pino，默认情况下写入stderr。

媒体处理

发送媒体：

  • 文件路径可以是绝对路径或相对路径
  • 从文件扩展名自动检测媒体类型(.jpg, .mp4, .mp3, .pdf等等）
  • 通过手动超控 mediaType 需要时使用参数
  • 图像、视频和文档支持字幕
  • 语音备忘：设置 ptt: true 以WhatsApp语音备忘的形式发送音频（按键通话）。需要OGG Opus格式

正在下载媒体：

  • 媒体通过Baileys下载 downloadContentFromMessage() 功能
  • 内容类型由消息结构决定
  • 根据MIME类型或内容类型推断文件扩展名
  • 如果输出目录不存在，则创建输出目录

重要说明

单会话限制

运行此MCP服务器将断开任何现有的WhatsApp Web会话。当此服务器连接时，您无法在其他地方使用WhatsApp Web。

服务条款风险

Baileys是一个反向工程的WhatsApp Web客户端。使用它可能会违反WhatsApp的服务条款。考虑：

  • 使用辅助号码或商业号码
  • 接受使用主要个人号码的风险
  • 首先在非关键环境中进行测试

JID格式

WhatsApp使用不同格式的JID（Jabber ID）地址：

  • 个人聊天： {phone_number}@s.whatsapp.net

    • 例子： 923001234567@s.whatsapp.net
    • 电话号码应包含国家代码，不含 + 或空间

  • 组： {group_id}@g.us

    • 例子： 120363039783372408@g.us
    • 组ID可以通过以下方式找到 list_groups

  • LID格式（现代组）： {id}@lid

    • 内部用于新组格式的参与者
    • 可能出现在 contextInfo.participant 领域

电话号码标准化

这 send_message 和 send_media 工具接受多种格式的电话号码：

  • 923001234567 （纯数字）
  • +92 300 123 4567 （格式化）
  • 92-300-123-4567 （破折号）

所有非数字字符都会自动删除；仅使用数字部分。

故障排除

“WhatsApp未连接”错误：

  • 检查MCP服务器是否正在运行（stderr应显示连接状态）
  • 跑 npm run login 重新验证
  • 验证您的手机是否安装了WhatsApp和互联网连接
  • 检查是否没有其他WhatsApp Web会话处于活动状态

二维码未出现：

  • 确保你正在跑步 npm run login （不是 npm run start)
  • 检查stderr输出是否可见（某些终端配置可能会抑制它）
  • 验证终端是否支持用于QR渲染的ANSI字符

未发送的邮件：

  • 验证收件人电话号码或组JID是否正确
  • 检查您的WhatsApp帐户是否有权向收件人发送消息
  • 检查MCP服务器stderr日志以获取详细的错误消息

媒体下载失败：

  • 确保消息ID和JID正确
  • 消息必须在本地存储中（仅限最近的消息）
  • 检查输出目录的文件系统权限
  • 验证消息是否确实包含可下载媒体

许可证

麻省理工学院

相关 MCP