WhatsApp MCP for Claude Desktop

WhatsApp MCP for Claude Desktop

Connect Claude Desktop to WhatsApp. Send & receive messages, manage groups, share media — all through natural conversation with Claude.

Features

• Zero-config first launch — auto-detects your WhatsApp Web session from Chrome
• Multi-profile — switch between WhatsApp accounts
• Full messaging — send, read, search, reply, forward, react
• Media support — send images/documents, download attachments
• Group management — create groups, add/remove members, get info
• Cross-platform — Windows, macOS, Linux
• Auto-reconnect — recovers from disconnections automatically

Quick Install

Windows

git clone https://github.com/Shloimy15e/whatsapp-mcp.git
cd whatsapp-mcp
powershell -ExecutionPolicy Bypass -File install.ps1

macOS / Linux

git clone https://github.com/Shloimy15e/whatsapp-mcp.git
cd whatsapp-mcp
chmod +x install.sh && ./install.sh

Manual Install

1. Clone this repo and cd into it
2. Run PUPPETEER_SKIP_DOWNLOAD=true npm install
3. Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "whatsapp": {
      "command": "node",
      "args": ["/full/path/to/whatsapp-mcp/server.mjs"]
    }
  }
}

1. Restart Claude Desktop

Requirements

• Node.js 18+ (download)
• Google Chrome (used by the WhatsApp Web engine)
• Claude Desktop (download)

How It Works

On first launch, the MCP server:

1. Scans your Chrome profiles for an existing WhatsApp Web session
2. If found, clones the session data so Chrome doesn't need to stay open
3. Connects to WhatsApp headlessly (no visible browser window)
4. If no session is found, you can ask Claude to set up a new one via QR code

Available Tools

| Tool | Description | |------|-------------| | whatsapp_setup | Manage profiles (add, remove, switch, scan Chrome, clone session) | | whatsapp_status | Connection status, uptime, platform info | | whatsapp_list_chats | List recent chats with unread counts | | whatsapp_read_messages | Read messages from a chat | | whatsapp_search_chats | Search chats by name or number | | whatsapp_send_message | Send text, reply, or media messages | | whatsapp_react | React to a message with an emoji | | whatsapp_forward_message | Forward a message to another chat | | whatsapp_download_media | Download media attachments | | whatsapp_get_contact_info | Get contact details | | whatsapp_get_group_info | Get group details and participants | | whatsapp_create_group | Create a new group | | whatsapp_group_add_participants | Add members to a group | | whatsapp_group_remove_participants | Remove members from a group | | whatsapp_leave_group | Leave a group |

Project Structure

whatsapp-mcp/
├── server.mjs          # Entry point — MCP server setup & auto-connect
├── lib/
│   ├── logger.mjs      # Logging & crash handlers
│   ├── platform.mjs    # Cross-platform helpers (Chrome paths, OS utils)
│   ├── config.mjs      # Config file management
│   ├── chrome.mjs      # Chrome profile detection
│   ├── clone.mjs       # Session cloning from Chrome
│   └── client.mjs      # WhatsApp client lifecycle & state
├── tools/
│   ├── setup.mjs       # Profile management tool
│   ├── status.mjs      # Connection status tool
│   ├── chat.mjs        # Chat tools (list, read, search, send)
│   ├── media.mjs       # Media tools (react, forward, download)
│   ├── contact.mjs     # Contact info tool
│   └── group.mjs       # Group management tools
├── install.ps1         # Windows installer
├── install.sh          # macOS/Linux installer
├── package.json
└── config.json         # Auto-generated profile config

Troubleshooting

"Chrome not found" — Install Google Chrome, or set the path manually in lib/platform.mjs.

QR code won't scan — Make sure Chrome is fully closed (check Task Manager / Activity Monitor). The WhatsApp Web engine needs exclusive access.

"WhatsApp not ready" — Ask Claude to run whatsapp_status for details. Try whatsapp_setup switch_profile name:default to reconnect.

Session expired — WhatsApp sessions expire after ~2 weeks of inactivity. Delete the .wwebjs_auth folder and re-authenticate.

License

MIT