Provides tools for sending, reading, and deleting WhatsApp messages with granular per-chat permissions, enabling programmatic interaction with WhatsApp chats and groups through WhatsApp Web.
zappy-mcp
WhatsApp MCP server for Claude Desktop, OpenCode, and other MCP clients. Send, read, and delete messages with granular per-chat permissions.
Built on whatsapp-web.js and the Model Context Protocol.
Table of Contents
Quick Start
Scan the QR with WhatsApp (Settings > Linked Devices > Link a Device).
How It Works
This server uses whatsapp-web.js, which runs a headless Chromium browser via Puppeteer to connect to WhatsApp Web. There's no official WhatsApp API for personal accounts, so this library automates the web interface.
Authentication Flow
First run: The server launches headless Chromium and opens WhatsApp Web
QR code: A browser window opens showing a QR code (auto-opens on an available port)
Scan: Open WhatsApp on your phone -> Settings -> Linked Devices -> Link a Device -> Scan the QR
Session saved: After successful scan, session credentials are stored locally
Future runs: The server reconnects automatically using saved credentials - no QR needed
Session Storage
The auth is stored globally, so you only authenticate once per machine. Different projects can use different permission configs while sharing the same WhatsApp session.
Re-authenticating
If you need to switch accounts or fix auth issues:
Security Notes
Session data in
~/.config/zappy-mcp/auth/grants full access to your WhatsApp - protect it like a passwordThe QR code is only shown locally in your browser, never transmitted
Each config file controls which chats the AI can access - use minimal permissions
MCP Setup
Claude Desktop
~/Library/Application Support/Claude/claude_desktop_config.json:
OpenCode
Project-level (.mcp.json in project root):
User-level (~/.config/opencode/mcp.json):
Permissions
By default, no chats are allowed. The AI cannot send, read, or delete messages until you explicitly grant access. This is a safety feature - you control exactly which conversations the AI can interact with.
Finding Chat IDs
First, connect WhatsApp and use the list_chats tool to discover your chat IDs:
Chat IDs look like:
Groups:
120363295812730408@g.usContacts:
14155551234@c.us(country code + phone number)
Config File
Create a config file (e.g., .zappy-mcp.json) with the chats you want to allow:
Permission Options
Field | Description | Default |
| Chat ID from | - |
| Human-readable label for your reference | - |
| Allow AI to send messages to this chat |
|
| Allow AI to read messages from this chat |
|
| Allow AI to delete its own messages (safety: off by default) |
|
Example Use Cases
Scenario | canSend | canRead | canDelete |
Full access |
|
|
|
Announcements only (no reading) |
|
|
|
Monitoring only (no sending) |
|
|
|
Send with ability to unsend mistakes |
|
|
|
Global Options
At the root level of your config:
Option | Description |
| Hide "no recipients configured" warnings at startup |
Tools
Status & Discovery
Tool | Description |
| Check WhatsApp connection status, shows config path and auth location |
| Show all permitted chats with their current permissions |
| List all WhatsApp chats with IDs - use this to find chat IDs for setup |
Messaging
send_message
Send a message to a chat. Requires canSend permission.
Parameter | Description |
| Chat ID (from |
| Text content to send |
get_messages
Fetch recent messages from a chat. Requires canRead permission.
Parameter | Description |
| Chat ID or phone number |
| Number of messages to fetch (default: 20) |
delete_message
Delete a message you sent. Requires canDelete permission. Only works on messages where fromMe: true.
Parameter | Description |
| Chat ID where the message exists |
| Message ID (get this from |
| If |
Troubleshooting
Messages not delivering
The WhatsApp client needs about 5 seconds after connecting to sync with the server. This is handled automatically, but if messages stay stuck in "pending" state, try restarting the MCP server.
Session/auth issues
If you're having trouble connecting, try clearing the auth data and scanning the QR code again:
Linux: Puppeteer/Chromium dependencies
whatsapp-web.js uses Puppeteer to run headless Chromium. On Linux, you may need to install system dependencies:
Account restrictions
WhatsApp does not officially support automation or bots on personal accounts. Excessive or abusive use may result in temporary or permanent account restrictions. Use responsibly and respect rate limits.
License
MIT