🚀 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 桌面应用程序

安装步骤如下：

1. 下载源代码包
2. 解压文件包
3. 打开终端，导航到解压目录
4. 运行命令：npm install
5. 成功安装后，在终端运行 npm start 开始服务

✨ 主要特性

1. 发送联系人消息

可以向 WhatsApp 联系人列表中的特定联系人发送文本消息，具体特点如下：

• 消息通过已连接的 WhatsApp 桌面应用程序传递
• 支持消息格式化，包括换行符
• 使用 AppleScript 自动化 WhatsApp 桌面界面

2. 检查 WhatsApp 状态（开发中）

验证 WhatsApp 应用程序是否当前运行，具备以下功能：

• 返回 WhatsApp 的当前运行状态
• 防止在尝试发送消息时出现错误

3. 列出最近联系人（开发中）

由于 WhatsApp 的隐私保护限制，此功能提供有限的可用性：

• 提醒用户有关 WhatsApp 的隐私限制
• 要求用户提供确切的联系人名称以进行消息传输

📦 安装指南

1. 下载源代码包
2. 解压文件包
3. 打开终端，导航到解压目录
4. 运行命令：npm install
5. 成功安装后，在终端运行 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 调用功能

集成指南

1. 安装并运行 WhatsApp MCP 服务器
2. 配置 Claude Desktop 的 MCP 工具设置
3. 添加以下内容到 app-settings.json：

   "mcp.tools.whatsapp": {
     "host": "localhost",
     "port": 3000,
     "timeout": 5000
   }
   

4. 在 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。