AI导哈

WhatsApp MCP 服务器

一个模型上下文协议（MCP）服务器，使大型语言模型能够通过WhatsApp Web界面与WhatsApp交互。

  • by fabienbutz
  • JavaScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 fabienbutz/whatsapp-mcp

使用说明

WhatsApp MCP服务器

一种模型上下文协议（MCP）服务器，使LLM能够通过WhatsApp Web界面与WhatsApp进行交互。适用于任何兼容MCP的客户端（克劳德桌面、克劳德代码等）。

警告：这使用了非官方的whatsapp-web.js库，违反了whatsapp的服务条款。使用风险由您自行承担——账户可能被封禁。

特性

  • 发送消息：向任何WhatsApp联系人或电话号码发送短信
  • 阅读消息：从任何聊天中获取消息历史记录
  • 联系人管理：列出和搜索联系人
  • 搜索：在聊天记录中搜索消息
  • 二维码显示：直接在Claude中查看二维码，便于身份验证
  • 消息交互：使用表情符号进行反应，引用回复，编辑和删除消息
  • 输入指示：显示聊天中的打字或录制状态
  • 媒体处理：发送和接收图像、文档和其他媒体
  • 语音转录：使用OpenAI Whisper转录语音信息
  • 自动恢复：检测浏览器崩溃并允许重新连接而无需重新认证

先决条件

  • Node.js 18或更高版本
  • WhatsApp帐户
  • Chrome/Chromium（由Puppeteer自动安装）

安装

# Clone the repository
git clone https://github.com/fabienbutz/whatsapp-mcp.git
cd whatsapp-mcp

# Install dependencies
npm install

# Build the project
npm run build

配置

克劳德桌面版

将此添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "whatsapp": {
      "command": "node",
      "args": ["/absolute/path/to/whatsapp-mcp/build/index.js"],
      "env": {
        "OPENAI_API_KEY": "sk-your-openai-key-here"
      }
    }
  }
}

备注：The OPENAI_API_KEY 是可选的，仅用于语音消息转录。

其他MCP客户端

对于其他MCP兼容客户端，请使用以下配置服务器：

  • 命令: node
  • 参数: ["/absolute/path/to/whatsapp-mcp/build/index.js"]

首次设置

  1. 启动MCP服务器（通过Claude Desktop或直接使用 npm start)
  2. 让克劳德检查WhatsApp的状态-它将显示一个二维码
  3. 在手机上打开WhatsApp
  4. 首选 设置→ 链接设备→ 链接设备
  5. 扫描二维码
  6. 一旦通过身份验证，会话将保存在本地 .wwebjs_auth/

可用工具

工具 说明
whatsapp_status 检查连接状态和触点数量
whatsapp_get_qr_code 显示二维码进行身份验证
whatsapp_send_message 向电话号码发送消息
whatsapp_send_to_contact 按姓名向联系人发送消息
whatsapp_list_contacts 列出所有已保存的联系人
whatsapp_find_contact 按姓名搜索联系人
whatsapp_get_messages 从特定聊天中获取消息
whatsapp_get_recent_messages 获取所有聊天记录中的最新消息
whatsapp_fetch_more_messages 加载更多聊天消息历史记录
whatsapp_search_messages 按文本搜索邮件
whatsapp_sync_history 请求历史同步
whatsapp_logs 查看服务器日志以进行调试
whatsapp_reconnect 如果浏览器崩溃，请重新连接（保持身份验证）
whatsapp_reset_auth 重置身份验证并扫描新的二维码
whatsapp_react 使用表情符号回复消息
whatsapp_reply 对特定消息的报价回复
whatsapp_delete_message 删除消息（适用于所有人或本地）
whatsapp_edit_message 编辑已发送的短信
whatsapp_typing_indicator 在聊天中显示打字/录音指示器
whatsapp_download_media 从消息中下载媒体（图像、视频、音频）
whatsapp_send_image 从URL或base64数据发送图像
whatsapp_send_document 从URL或base64数据发送文档/文件
whatsapp_transcribe_audio 使用OpenAI Whisper转录语音信息

使用示例

连接后，您可以问Claude以下问题：

  • “显示我最近的WhatsApp消息”
  • “发送'你好！'至+49151234567”
  • “给约翰发个信息，说我会迟到”
  • “[姓名]最近10条消息是什么？”
  • “在我的WhatsApp中搜索有关“会议”的消息”
  • “检查我的WhatsApp连接状态”
  • “将此图像发送给John”（带图像URL）
  • “对[姓名]的最后一条消息竖起大拇指”
  • “回复[姓名]最后一条表示感谢的消息”
  • “删除我发送给[姓名]的最后一条消息”
  • “转录来自[姓名]的最后一条语音信息”
  • “[名字]在他们的语音信息中说了什么？”

电话号码格式

电话号码应采用国际格式 没有 领先者 +:

  • 德语： 4915123456789 （不是 +4915123456789)
  • 我们： 14155551234

速率限制

为了降低禁令风险：

  • 避免每天发送超过10-20条自动消息
  • 不要向未知联系人发送消息
  • 主要用于回复收到的消息
  • 在自动化之前，让您的帐户在正常使用情况下“老化”

故障排除

二维码未显示

  • 让克劳德打电话 whatsapp_get_qr_code -它将把二维码显示为图像
  • 检查 whatsapp_logs 对于错误

身份验证失败

  • 删除 .wwebjs_auth/ 文件夹并重新启动
  • 确保WhatsApp Web未在浏览器中打开
  • 删除任何挥之不去的Chrome进程： pkill -f "Google Chrome for Testing"

邮件未发送

  • 检查 whatsapp_logs 对于特定错误
  • 最有可能的WhatsApp Web API更改-请参阅 CLAUDE.md 了解已知问题和修复方法

浏览器崩溃/“分离框架”错误

如果 whatsapp_status 显示 browser_crashed 或者您会看到“分离帧”错误：

  1. 跑 whatsapp_reconnect -这将重新启动浏览器，同时保持您的身份验证会话
  2. 如果失败，请使用 whatsapp_reset_auth 扫描新的二维码
  3. 作为最后的手段，重新启动Claude Desktop

木偶错误

  • 确保Chrome/Chromium可用
  • 在Linux上，您可能需要其他依赖项：
    apt-get install -y chromium-browser

发展

# Run in development mode with hot reload
npm run dev

# Build for production
npm run build

# Run built version
npm start

看 CLAUDE.md 了解whatsapp-web.js的开发最佳实践和已知问题。

许可证

麻省理工学院-见 许可证

免责声明

此项目与WhatsApp或Meta无关。使用非官方客户可能会导致您的帐户被禁止。这仅供个人使用和实验。

相关 MCP