Whatsapp Desktop

🚀 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。