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

MCP Servers