Enables reading messages, searching conversations, retrieving group statistics, and sending messages to WhatsApp groups.
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-mcpSummarize the last 24 hours of messages in the Engineering group"
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
An MCP (Model Context Protocol) server that connects Claude to WhatsApp. Read messages, search conversations, get group stats, and send messages — all through Claude Code or any MCP client.
Built on Baileys (WhatsApp Web API) and the MCP SDK.
Features
Read group messages with flexible time ranges (24h, 7d, 2w, or ISO dates)
Full-text search across all messages, optionally filtered by group
Group stats — activity breakdown, top contributors, hourly/daily patterns, media counts
Per-member stats — message counts, media usage, active hours
Send messages to any WhatsApp group
History sync — request older messages from WhatsApp servers
Persistent store — messages are saved to disk and survive restarts
Quick Setup
1. Install dependencies
npm install2. Pair WhatsApp (first time only)
npm run devA QR code will appear in your terminal. Scan it with WhatsApp on your phone (Settings > Linked Devices > Link a Device). Auth state is saved in auth_info/, so you only need to do this once. You can stop the process after pairing.
3. Configure MCP
Add to your Claude Code MCP config (.mcp.json in your project or ~/.claude.json):
{
"mcpServers": {
"whatsapp": {
"type": "stdio",
"command": "npx",
"args": ["tsx", "/path/to/whatsapp-mcp/src/index.ts"]
}
}
}Claude Code will start the server automatically when it needs WhatsApp tools — you don't need to run it separately.
Available Tools
Tool | Description |
| Check WhatsApp connection state, store size, group count |
| List all groups with name, JID, participant count, message count |
| Group details: members, admins, description, creation date |
| Get messages from a group with time range filtering |
| Full-text search across messages, optionally scoped to a group |
| Activity stats: message counts, top contributors, hourly/daily patterns |
| Per-member breakdown: messages, media, active hours |
| Request older messages from WhatsApp servers (async) |
| Send a text message to a group |
Architecture
src/
├── index.ts # Entry point — starts WhatsApp + MCP server
├── whatsapp.ts # Baileys connection, message store, history sync
├── mcp-server.ts # MCP tool registrations
├── store.ts # Message querying and stats computation
└── tools/
├── groups.ts # list_groups, get_group_info
├── messages.ts # fetch_messages, search_messages
├── stats.ts # get_group_stats, get_member_stats
└── send.ts # send_messageMessages are stored in-memory and flushed to store/message-store.json every 30 seconds. History sync messages from WhatsApp are automatically ingested on connection.
Scripts
scripts/cron-summary.sh— Daily summary cron job. Uses Claude CLI to fetch and summarize all active group conversations.scripts/find-group.ts— Utility to look up a group JID by name.
Skills
The .claude/skills/ directory contains reusable Claude Code skills:
summarize-group— Fetches messages and stats for a group, then produces a concise summary of activity. Usage:/summarize-group [group name] [time range]
Development
npm run dev # Run with tsx (hot reload)
npm run build # Compile TypeScript
npm run start # Run compiled outputLicense
MIT