# 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](https://github.com/WhiskeySockets/Baileys) (WhatsApp Web API) and the [MCP SDK](https://modelcontextprotocol.io).

## 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

```bash
npm install
```

### 2. Pair WhatsApp (first time only)

```bash
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`):

```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

```bash
npm run dev      # Run with tsx (hot reload)
npm run build    # Compile TypeScript
npm run start    # Run compiled output
```

## License

MIT