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
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.