🚀 WhatsApp MCP 服务器
WhatsApp MCP（模型上下文协议）服务器是一个基于 Node.js 的应用程序，它能让你通过 AppleScript 自动化，在 macOS 上与已安装的 WhatsApp 桌面应用程序进行编程交互。无需手动操作 WhatsApp 用户界面，就能实现发送消息和检查 WhatsApp 状态等功能。
🚀 快速开始
若要使用 WhatsApp MCP 服务器，你需要满足以下要求：
- Windows、macOS 或 Linux 系统
- Node.js 14.17.0 或更高版本
- npm 6.0.0 或更高版本
- 安装并登录到 WhatsApp 桌面应用程序
安装步骤如下：
- 下载源代码包
- 解压文件包
- 打开终端，导航到解压目录
- 运行命令：
npm install - 成功安装后，在终端运行
npm start开始服务
✨ 主要特性
1. 发送联系人消息
可以向 WhatsApp 联系人列表中的特定联系人发送文本消息，具体特点如下：
- 消息通过已连接的 WhatsApp 桌面应用程序传递
- 支持消息格式化，包括换行符
- 使用 AppleScript 自动化 WhatsApp 桌面界面
2. 检查 WhatsApp 状态（开发中）
验证 WhatsApp 应用程序是否当前运行，具备以下功能：
- 返回 WhatsApp 的当前运行状态
- 防止在尝试发送消息时出现错误
3. 列出最近联系人（开发中）
由于 WhatsApp 的隐私保护限制，此功能提供有限的可用性：
- 提醒用户有关 WhatsApp 的隐私限制
- 要求用户提供确切的联系人名称以进行消息传输
📦 安装指南
- 下载源代码包
- 解压文件包
- 打开终端，导航到解压目录
- 运行命令：
npm install - 成功安装后，在终端运行
npm start开始服务
💻 使用示例
基础用法
发送消息
curl -X POST http://localhost:3000/api/send-message \
-H "Content-Type: application/json" \
-d '{"to": "+1234567890", "message": "你好！"}'
检查状态
curl http://localhost:3000/api/status
📚 详细文档
- 参考项目根目录下的
docs文件夹中的 API 文档 - 通过配置文件自定义服务器参数
- 使用 RESTful API 或 CLI 调用功能
集成指南
- 安装并运行 WhatsApp MCP 服务器
- 配置 Claude Desktop 的 MCP 工具设置
- 添加以下内容到
app-settings.json："mcp.tools.whatsapp": { "host": "localhost", "port": 3000, "timeout": 5000 } - 在 Claude Desktop 中启用 MCP 工具插件
🔧 技术细节
使用工具
- @modelcontextprotocol/sdk - MCP 服务器和 stdio 运输
- Zod - 模式验证
- Node.js 内置模块（child_process、util、fs）
- AppleScript 实现 macOS 自动化
架构
- 使用模型上下文协议（MCP）实现工具间标准化通信
- 采用 stdio 运输进行通信
- 执行 AppleScript 命令以与 WhatsApp 桌面应用程序交互
- 实现全面错误日志记录
实现细节
- 使用 Node.js 开发，支持异步非阻塞编程模型
- 基于事件驱动架构实现高效通信
- 通过模块化设计提高代码复用性
- 遵循标准软件开发规范和命名惯例
工具细节
whatsapp-send-message：通过 WhatsApp 桌面应用程序发送消息whatsapp-get-status：获取 WhatsApp 的当前运行状态whatsapp-list-contacts：列出最近使用的 WhatsApp 联系人列表
📄 许可证
本项目采用 MIT 许可证。
⚠️ 重要提示
此项目未获得 WhatsApp Inc. 或 Meta Platforms, Inc. 的官方支持。使用前请仔细阅读 WhatsApp 的服务条款，并自行承担风险。
💡 使用建议
- 服务器与您的个人 WhatsApp 帐户交互，消息将从您的帐户发送并显示为您发送，请仅在受信任的环境中使用。
- 由于该项目依赖 AppleScript，目前仅限 macOS 系统使用。
- 受限于 WhatsApp UI 更新对联系人选择的影响以及隐私保护，可能无法访问完整的联系人列表。
- 若要使用相关功能，需先配置 Claude Desktop。