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.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@WhatsApp MCP Serversend 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-mcp2. 安装依赖
npm install3. 设置 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 | 描述 |
| 搜索联系人 |
| 列出聊天列表 |
| 获取聊天详情 |
| 列出消息 |
| 搜索消息内容 |
| 发送消息 |
| 获取联系人详情 |
| 获取连接状态 |
| 触发历史同步 |
📊 数据库 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 |
跨实例使用 | ❌ 数据无法共享 | ✅ 所有实例共享数据 |
🐛 故障排除
QR 码不显示
检查终端是否支持二维码显示，或尝试使用其他终端。
连接断开
Baileys 会自动重连（最多5次）。如需重新登录，删除 auth_info/ 目录后重启。
消息同步慢
首次同步可能需要较长时间，取决于消息历史数量。后续为增量同步。
📄 许可证
MIT
🙏 致谢
Baileys - WhatsApp Web API
Model Context Protocol - MCP 协议
Supabase - 开源 Firebase 替代方案
This server cannot be installed
Resources
Looking for Admin?
Admins can modify the Dockerfile, update the server description, and track usage metrics. If you are the server author, to access the admin panel.