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 install

2. Pair WhatsApp (first time only)

npm run dev

A 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
connection_status	Check WhatsApp connection state, store size, group count
list_groups	List all groups with name, JID, participant count, message count
get_group_info	Group details: members, admins, description, creation date
fetch_messages	Get messages from a group with time range filtering
search_messages	Full-text search across messages, optionally scoped to a group
get_group_stats	Activity stats: message counts, top contributors, hourly/daily patterns
get_member_stats	Per-member breakdown: messages, media, active hours
request_history	Request older messages from WhatsApp servers (async)
send_message	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_message

Messages 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 output

License

MIT