io.github.kalki-kgp/whatsapp-macos

Check it out on https://mcp.paperknife.app/

WhatsApp MCP for macOS

A Model Context Protocol server that connects Claude to your WhatsApp. Ask Claude to catch you up on unread chats, search your message history, or send a reply.

Reading works in about a minute with no QR scan and no Node.js. Sending is optional and needs one extra step.

Features

Search contacts by name or phone number. Read chat history with date filtering. List recent conversations with unread counts. Summarize everything you haven't read yet. Send replies and receive incoming messages once the bridge is connected.

Requirements

• macOS with the WhatsApp desktop app installed and logged in
• Node.js 18+, only if you want to send messages

You don't need to install Python. uvx fetches a suitable version on its own.

Installation

Install uv if you don't have it:

curl -LsSf https://astral.sh/uv/install.sh | sh

That's the whole install. uvx downloads the server on first launch, so there's no virtualenv to create and no pip install step. Go to the next section to point Claude at it.

From source

git clone https://github.com/kalki-kgp/whatsapp-mcp.git
cd whatsapp-mcp
uv venv && uv 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.

2. Find the full path to uvx:

    which uvx

3. Add the WhatsApp MCP server, pasting that path as the command:

    {
      "mcpServers": {
        "whatsapp": {
          "command": "/Users/YOU/.local/bin/uvx",
          "args": ["whatsapp-mcp-macos"]
        }
      }
    }

   Use the absolute path, not bare uvx. Claude Desktop starts with a minimal PATH that doesn't include ~/.local/bin, so a bare command name is the most common reason the server never appears.

4. Restart Claude Desktop with Cmd+Q, then reopen. Closing the window is not enough.
5. Click the MCP tools icon in the chat input and check that "whatsapp" is listed.
6. 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": "/Users/YOU/.local/bin/uvx",
      "args": ["whatsapp-mcp-macos"]
    }
  }
}

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

2. Ask Claude to check connection:
   • "Check WhatsApp status"
3. If it shows a QR code, open the data URL in a browser and scan with your phone
4. 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, so they work offline and need no bridge.

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. The server reads messages 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