Whatsapp MCP Ts

🚀 WhatsApp MCP 服務器使用指南（中文版）

本項目是一個基於 Node.js 的單進程應用程序，主要用於連接 WhatsApp Web API 並提供 MCP（Model Context Protocol）服務，為開發者與 WhatsApp 服務交互提供便利，還能通過 MCP 協議集成到 AI 應用程序中。

✨ 主要特性

• 認證管理：藉助 Baileys 庫處理 WhatsApp 賬號的登錄和認證，支持掃描 QR 碼進行初始登錄，後續還能自動重連。
• 數據存儲：所有聊天記錄、消息內容及元數據都存儲在本地 SQLite 數據庫（路徑為 ./data/whatsapp.db），認證信息和敏感數據存於 ./auth_info/ 目錄，避免意外提交到版本控制系統。
• MCP 接口：提供多個 MCP 工具函數，如搜索聯繫人、列出聊天記錄、發送消息等，支持與 AI 客戶端（如 Claude Desktop 或 Cursor）通過標準輸入輸出進行集成。

📦 安裝指南

環境要求

• Node.js 版本需 23.10.0 及以上。
• 安裝依賴，執行以下命令：

npm install

啟動服務器

運行以下命令啟動 MCP 服務：

node src/main.ts

首次啟動時，程序會生成 QR 碼鏈接並在控制檯輸出，使用手機掃描該鏈接完成登錄。

配置 AI 客戶端

對於 Claude Desktop

• 創建配置文件 claude_desktop_config.json：

{
    "servers": [
        {
            "name": "whatsapp",
            "command": "node",
            "args": ["{{PROJECT_PATH}}/src/main.ts"],
            "stdio": "pipe"
        }
    ]
}

• 替換 {{PROJECT_PATH}} 為實際項目路徑。

對於 Cursor

• 創建配置文件 mcp.json：

{
    "servers": [
        {
            "name": "whatsapp",
            "command": "node",
            "args": ["{{PROJECT_PATH}}/src/main.ts"],
            "stdio": "pipe"
        }
    ]
}

💻 使用示例

基礎用法

在 AI 客戶端中調用以下工具：

• searchContacts：搜索聯繫人。
• listChats：列出最近聊天記錄。
• readMessages：讀取消息內容。
• sendMessage：發送新消息。

🔧 技術細節

核心組件

• 使用 @whiskeysockets/baileys 庫與 WhatsApp Web API 通信。
• 使用 SQLite 數據庫存儲消息和聊天記錄。
• 基於 MCP 協議提供標準輸入輸出接口，供 AI 客戶端調用。

技術棧

• 開發語言：TypeScript
• 運行時環境：Node.js（版本 23.10.0 及以上）
• 數據庫：SQLite（通過 node:sqlite 庫實現）
• 日誌記錄：Pino
• 參數驗證：Zod

📚 詳細文檔

故障排除

QR 碼問題

• 若無法自動打開 QR 碼鏈接，可查看控制檯輸出獲取 URL 並手動訪問，然後使用手機上的 WhatsApp 應用掃描 QR 碼完成登錄。

登錄失效

若出現登錄失效，可按以下步驟操作：

1. 停止當前運行的 MCP 服務。
2. 刪除 ./auth_info/ 目錄下的所有文件。
3. 重新啟動服務並完成新的 QR 碼掃描流程。

數據庫問題

• 若 SQLite 數據庫文件損壞，可嘗試恢復或重建數據庫。
• 要確保項目目錄下存在 data/ 和 auth_info/ 文件夾。

日誌記錄

程序使用 Pino 庫記錄日誌，默認輸出到控制檯，可通過配置 Pino 的選項來調整日誌級別和格式。 例子：

import { log } from 'pino';

const logger = log({ level: 'info' });

logger.info('啟動 WhatsApp MCP 服務');

參數驗證

使用 Zod 庫對輸入參數進行嚴格驗證，確保 API 調用的安全性和可靠性。 示例：

import { z } from 'zod';

type SendMessageParams = {
    text: string;
};

const validateMessage = z.object({
    text: z.string().min(1)
});

async function sendMessage(params: SendMessageParams) {
    const validated = await validateMessage.parseAsync(params);
    // 處理消息
}

總結

此 WhatsApp MCP 服務器項目為開發者提供了強大的工具集，能方便地與 WhatsApp 服務進行交互，並通過 MCP 協議集成到 AI 應用程序中。希望這份指南能幫助您順利部署和使用該服務。