WhatsApp MCP for macOS

<!-- mcp-name: io.github.kalki-kgp/whatsapp-macos -->

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

<p align="center"> <img src="https://img.shields.io/badge/platform-macOS-blue" alt="macOS"> <img src="https://img.shields.io/badge/MCP-1.0-green" alt="MCP 1.0"> <img src="https://img.shields.io/badge/license-MIT-lightgrey" alt="MIT License"> </p>

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

1. Open config file:

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

If it doesn't exist, create it.

1. Add the WhatsApp MCP server:

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

1. Restart Claude Desktop (Cmd+Q, then reopen)

1. Look for the MCP tools icon (🔨) in the chat input — click it to verify "whatsapp" is listed

1. 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)

1. Start the WhatsApp bridge:

   cd bridge && npm install && npm start

1. Ask Claude to check connection:

• "Check WhatsApp status"

1. If it shows a QR code, open the data URL in a browser and scan with your phone

1. Once connected, you can send:

• "Send a message to Mom saying I'll be late"
• "Reply to John with 'sounds good'"

Tools

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