WhatsApp MCP for macOS

A Model Context Protocol server that connects Claude to your WhatsApp. Read messages, search contacts, send replies — all through natural conversation.

Features

Search contacts — Find anyone by name or phone number
Read messages — Get chat history with date filtering and search
List chats — See recent conversations with unread counts
Send messages — Reply directly through Claude (with QR authentication)
Real-time incoming — Get messages as they arrive

Requirements

macOS with WhatsApp desktop app installed and logged in
Python 3.10+
Node.js 18+ (for sending messages)

Installation

Using pip

pip install whatsapp-mcp-macos

From source

git clone https://github.com/kalki-kgp/whatsapp-mcp.git
cd whatsapp-mcp
pip install -e .

Connect to Claude Desktop

Open config file:

open ~/Library/Application\ Support/Claude/claude_desktop_config.json

If it doesn't exist, create it.

Add the WhatsApp MCP server:

{
  "mcpServers": {
    "whatsapp": {
      "command": "python3",
      "args": ["-m", "whatsapp_mcp"]
    }
  }
}

Restart Claude Desktop (Cmd+Q, then reopen)
Look for the MCP tools icon (🔨) in the chat input — click it to verify "whatsapp" is listed
Start chatting:
- "Show my recent WhatsApp chats"
- "Search messages for dinner plans"

Connect to Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "whatsapp": {
      "command": "python3",
      "args": ["-m", "whatsapp_mcp"]
    }
  }
}

Restart Cursor and use WhatsApp tools in the AI chat.

Usage

Reading messages (works immediately)

Just ask Claude:

"Show my recent WhatsApp chats"
"Search for messages about dinner"
"What did John say yesterday?"
"Catch me up on unread messages"

Sending messages (requires bridge)

Start the WhatsApp bridge:
```
cd bridge && npm install && npm start
```
Ask Claude to check connection:
- "Check WhatsApp status"
If it shows a QR code, open the data URL in a browser and scan with your phone
Once connected, you can send:
- "Send a message to Mom saying I'll be late"
- "Reply to John with 'sounds good'"

Tools

Tool	Description	Requires Bridge
`whatsapp_status`	Check connection, get QR if needed	No
`whatsapp_search_contacts`	Search contacts by name/phone	No
`whatsapp_list_chats`	List recent conversations	No
`whatsapp_get_messages`	Get messages from a chat	No
`whatsapp_search_messages`	Search across all chats	No
`whatsapp_unread`	Get unread message summary	No
`whatsapp_send`	Send a message	Yes
`whatsapp_incoming`	Get real-time incoming messages	Yes

How it works

Claude ──MCP──▶ WhatsApp MCP Server
                       │
                       ├──▶ Local SQLite DBs (read messages)
                       │    ~/Library/Group Containers/group.net.whatsapp.WhatsApp.shared/
                       │
                       └──▶ WhatsApp Bridge (:3010) ──▶ WhatsApp Web
                            (for sending)

Read operations query the local WhatsApp database directly — fast and works offline.

Send operations go through the bridge, which connects to WhatsApp Web using Baileys.

Development

# Clone
git clone https://github.com/kalki-kgp/whatsapp-mcp.git
cd whatsapp-mcp

# Install in dev mode
pip install -e ".[dev]"

# Run server
python -m whatsapp_mcp

Privacy

All data stays local — messages are read from your own WhatsApp database
No data is sent to external servers (except WhatsApp Web when sending)
The MCP server runs locally on your machine

License

MIT

whatsapp-macos

Quick Install