WhatsApp MCP for macOS
Enables Claude to interact with WhatsApp on macOS through the Model Context Protocol. It allows reading messages, searching contacts, listing chats, and sending replies via natural conversation.
Ask AI about WhatsApp MCP for macOS
Powered by Claude Β· Grounded in docs
I know everything about WhatsApp MCP for macOS. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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.jsonIf 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
