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.

Quick Start
How It Works
MCP Setup
Permissions
Tools
Troubleshooting

Quick Start

git clone https://github.com/yourname/zappy-mcp.git
cd zappy-mcp
npm install
node src/index.js  # Opens browser with QR code

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

~/.config/zappy-mcp/
  auth/           # WhatsApp session data (shared across all configs)

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:

rm -rf ~/.config/zappy-mcp/auth
node src/index.js  # Opens QR code again

Security Notes

Session data in ~/.config/zappy-mcp/auth/ grants full access to your WhatsApp - protect it like a password
The 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:

{
  "mcpServers": {
    "zappy-mcp": {
      "command": "node",
      "args": ["/path/to/zappy-mcp/src/index.js", "--config", "/path/to/config.json"]
    }
  }
}

OpenCode

Project-level (.mcp.json in project root):

{
  "mcpServers": {
    "zappy-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/zappy-mcp/src/index.js", "--config", ".zappy-mcp.json"]
    }
  }
}

User-level (~/.config/opencode/mcp.json):

{
  "mcpServers": {
    "zappy-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/zappy-mcp/src/index.js", "--config", "~/.config/zappy-mcp/config.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:

list_chats()              # All chats
list_chats(groupsOnly: true)   # Only groups

Chat IDs look like:

Groups: 120363295812730408@g.us
Contacts: 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:

{
  "allowed": [
    {
      "id": "120363295812730408@g.us",
      "name": "Work Group",
      "canSend": true,
      "canRead": true,
      "canDelete": false
    },
    {
      "id": "14155551234@c.us",
      "name": "Alice",
      "canSend": true,
      "canRead": true,
      "canDelete": true
    }
  ]
}

Permission Options

Field	Description	Default
`id`	Chat ID from `list_chats` (required)	-
`name`	Human-readable label for your reference	-
`canSend`	Allow AI to send messages to this chat	`true`
`canRead`	Allow AI to read messages from this chat	`true`
`canDelete`	Allow AI to delete its own messages (safety: off by default)	`false`

Example Use Cases

Scenario	canSend	canRead	canDelete
Full access	`true`	`true`	`true`
Announcements only (no reading)	`true`	`false`	`false`
Monitoring only (no sending)	`false`	`true`	`false`
Send with ability to unsend mistakes	`true`	`true`	`true`

Global Options

At the root level of your config:

{
  "suppressWarnings": true,
  "allowed": [...]
}

Option	Description
`suppressWarnings`	Hide "no recipients configured" warnings at startup

Tools

Status & Discovery

Tool	Description
`get_status`	Check WhatsApp connection status, shows config path and auth location
`list_allowed`	Show all permitted chats with their current permissions
`list_chats`	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
`to`	Chat ID (from `list_chats`) or phone number with country code
`message`	Text content to send

get_messages

Fetch recent messages from a chat. Requires canRead permission.

Parameter	Description
`chatId`	Chat ID or phone number
`limit`	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
`chatId`	Chat ID where the message exists
`messageId`	Message ID (get this from `get_messages` response)
`forEveryone`	If `true`, deletes for all participants. If `false`, only hides it for you. (default: true)

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:

rm -rf ~/.config/zappy-mcp/auth
node src/index.js

Linux: Puppeteer/Chromium dependencies

whatsapp-web.js uses Puppeteer to run headless Chromium. On Linux, you may need to install system dependencies:

sudo apt-get install -y libgbm-dev libasound2 libatk1.0-0 libcups2 libxss1 libnss3 libgtk-3-0

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

Zappy MCP