mcp-whatsapp

WhatsApp MCP Server — connect AI agents to WhatsApp as a regular user.

Overview

MCP (Model Context Protocol) server that connects AI agents to WhatsApp through the multi-device API. Works as a regular WhatsApp user — not a business bot.

Built with Baileys, Bun, and TypeScript.

⚠️ Disclaimer: This project uses an unofficial WhatsApp API. Your account could be restricted or banned by WhatsApp. Use a secondary phone number. We are not responsible for any account actions taken by WhatsApp.

Related MCP server: WhatsApp Business API MCP Server

Features

• 🔌 MCP Protocol — works with Claude Desktop, Cursor, and any MCP client

• 💬 Messages — send, read, edit, delete, forward, react, polls, star

• 📎 Media — images, videos, documents, stickers, voice notes, audio, locations, contacts

• 👥 Groups — create, manage members, promote/demote admins, invite links, settings

• 🏘️ Communities — create, link/unlink groups, manage members

• 📢 Channels — create, follow/unfollow, mute newsletters

• 🏷️ Labels — label chats and messages (WhatsApp Business)

• 🔒 Privacy — last seen, profile photo, online status, read receipts, group add

• 👤 Profile — update name, status, picture, business profiles, call links

• 🗂️ Chats — list, search, archive, mute, pin, mark read, disappearing messages

• 🔐 Machine-bound sessions — encrypted with hardware ID, useless if copied to another device

• 📦 Single binary — no Node.js, no npm, just download and run

Quick Start

Download binary

Grab the latest release for your platform from GitHub Releases.

# Linux
chmod +x mcp-whatsapp-linux-x64
./mcp-whatsapp-linux-x64

# macOS
chmod +x mcp-whatsapp-darwin-arm64
./mcp-whatsapp-darwin-arm64

Build from source

git clone https://github.com/gridmint/mcp-whatsapp.git
cd mcp-whatsapp
bun install
bun run build
./mcp-whatsapp

Connect to Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "whatsapp": {
      "command": "/path/to/mcp-whatsapp"
    }
  }
}

Tools (77)

Messages (10)

Chats (7)

Contacts (5)

Groups (13)

Media (7)

Channels / Newsletters (6)

Privacy (7)

Communities (11)

Labels (4)

Profile & Misc (6)

Status (1)

Rate Limiting

Built-in sliding-window rate limiter protects your account from bans:

• Global: 30 write operations per minute

• Per-chat: 10 write operations per minute

• Read operations (list, search, get) are not rate-limited

• Exceeding limits returns a clear error with retry timing

Authentication

On first run, a QR code is displayed in the terminal. Scan it with WhatsApp on your phone:

1. Open WhatsApp → Settings → Linked Devices → Link a Device

2. Scan the QR code

Session is saved to ~/.mcp-whatsapp/auth/ — you won't need to scan again unless you log out.

Security

Session files are encrypted at rest (AES-256-GCM). By default, the encryption key is derived from your machine's hardware ID — no configuration needed.

• ✅ On your machine — works automatically, no extra steps

• ❌ Copied to another machine — can't decrypt, must scan QR again

• ❌ Stolen backup — encrypted, useless without the original hardware

Optionally, set your own encryption key via environment variable:

export MCP_WHATSAPP_SESSION_KEY=my-secret-key

This is useful for Docker containers, CI, or when you want to control the key yourself. If set, it takes priority over the machine ID.

Additional recommendations:

• Use a secondary phone number — your main account stays safe

• Check Linked Devices in WhatsApp periodically

• Keep your machine secure (disk encryption, strong passwords)

Development

bun install          # install dependencies
bun run dev          # run in development mode
bun run lint         # check code with Biome
bun run lint:fix     # auto-fix lint issues
bun run format       # format code
bun test             # run tests

Roadmap

• Group management (v0.2.0)

• Stickers, GIFs, voice messages (v0.2.0)

• Newsletters/Channels (v0.2.0)

• Privacy settings (v0.2.0)

• Polls (v0.2.0)

• Community management (v0.3.0)

• Business features (labels) (v0.3.0)

• Profile management (v0.3.0)

• Call link creation (v0.3.0)

• Disappearing messages (v0.3.0)

• Status/Stories (view and post)

• Product catalogs

• Rate limiting (ban protection)

License

MIT — see LICENSE.

Related

• mcp-telegram — Telegram MCP server by the same team