Which integrations are available for this server?

Uses Supabase for cloud storage and persistence of WhatsApp messages, contacts, chat history, and media metadata, utilizing Row Level Security (RLS) to ensure multi-user data isolation. Provides tools to interact with WhatsApp, including searching contacts, listing chats, sending messages, searching message history, and synchronizing historical data.

How do I use WhatsApp MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@WhatsApp MCP Server send a message to Alice saying I'm running 5 minutes late" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

WhatsApp MCP Server

一个功能完整的 WhatsApp MCP (Model Context Protocol) 服务器，支持多用户、云存储 (Supabase) 和完整的历史消息同步。

✨ 特性

🔗 MCP 协议支持 - 与 OpenClaw、Claude Desktop、Cursor 等兼容
👥 多用户支持 - 每个用户独立的 WhatsApp 连接和数据隔离
☁️ Supabase 云存储 - 消息、联系人、聊天记录持久化到云端
📜 历史消息同步 - 自动同步旧消息，支持增量更新
🔍 全文搜索 - 支持消息内容搜索
📎 媒体文件支持 - 图片、视频、文档、语音消息处理
🔐 安全隔离 - 基于 Supabase RLS 的行级安全控制

📁 项目结构

whatsapp-mcp-server/
├── src/
│   ├── index.ts              # 主入口
│   ├── db/
│   │   └── supabase.ts       # Supabase 数据库操作
│   ├── whatsapp/
│   │   ├── client.ts         # Baileys WhatsApp 客户端
│   │   └── message-handler.ts # 消息处理器
│   ├── tools/
│   │   └── index.ts          # MCP Tools 实现
│   └── types/
│       └── index.ts          # TypeScript 类型定义
├── supabase/
│   └── migrations/
│       └── 001_initial.sql   # 数据库初始化脚本
├── package.json
├── tsconfig.json
└── README.md

🚀 快速开始

1. 克隆仓库

git clone https://github.com/caseyklai/whatsapp-mcp.git
cd whatsapp-mcp

2. 安装依赖

npm install

3. 设置 Supabase

在 Supabase 创建新项目
在 SQL Editor 中执行 supabase/migrations/001_initial.sql
获取 Project URL 和 Service Role Key (Settings > API)

4. 配置环境变量

export SUPABASE_URL="your-supabase-url"
export SUPABASE_SERVICE_KEY="your-service-role-key"
export WHATSAPP_PHONE_NUMBER="your-phone-number"
export WHATSAPP_AUTH_USER_ID="optional-auth-user-id"

5. 构建并运行

npm run build
node dist/index.js

首次运行会显示 QR 码，使用 WhatsApp 扫描即可登录。

🔧 与 OpenClaw 集成

在 OpenClaw 配置中添加 MCP Server：

{
  "mcpServers": {
    "whatsapp": {
      "command": "node",
      "args": ["/path/to/whatsapp-mcp/dist/index.js"],
      "env": {
        "SUPABASE_URL": "your-supabase-url",
        "SUPABASE_SERVICE_KEY": "your-service-role-key",
        "WHATSAPP_PHONE_NUMBER": "your-phone-number"
      }
    }
  }
}

🛠️ 可用 Tools

Tool	描述
`whatsapp_search_contacts`	搜索联系人
`whatsapp_list_chats`	列出聊天列表
`whatsapp_get_chat`	获取聊天详情
`whatsapp_list_messages`	列出消息
`whatsapp_search_messages`	搜索消息内容
`whatsapp_send_message`	发送消息
`whatsapp_get_contact`	获取联系人详情
`whatsapp_get_connection_status`	获取连接状态
`whatsapp_sync_history`	触发历史同步

📊 数据库 Schema

核心表

wa_users - 用户信息及认证
wa_chats - 聊天会话
wa_messages - 消息记录
wa_contacts - 联系人
wa_media - 媒体文件元数据
wa_sync_logs - 同步日志
wa_webhook_events - Webhook 事件队列

🔒 安全特性

使用 Supabase Row Level Security (RLS) 确保用户数据隔离
认证信息本地存储 (auth_info/ 目录)
支持 OAuth 集成

📝 与 OpenClaw 内置 WhatsApp 对比

功能	OpenClaw 内置	MCP Server
历史消息获取	❌ 无法获取旧消息	✅ 自动同步完整历史
数据存储	❌ 本地/内存	✅ Supabase 云端持久化
多用户支持	❌ 单机版	✅ 完整多用户架构
全文搜索	❌ 有限	✅ 数据库全文搜索
媒体文件	❌ 临时存储	✅ 云存储 + CDN
跨实例使用	❌ 数据无法共享	✅ 所有实例共享数据