WhatsApp MCP Server

A native Model Context Protocol (MCP) server for WhatsApp on macOS.

This server bridges local WhatsApp Catalyst SQLite storage (ChatStorage.sqlite) with native OS messaging, enabling AI agents to read conversations, search message history, inspect media attachments, and send/draft messages with hardware-enforced biometric authorization (Apple Touch ID / Windows Hello).

Key Features

• Read-Only SQLite Storage Parsing: Connects directly to WhatsApp's sandboxed CoreData SQLite database using URI mode (file:...?mode=ro) with read-only pragmas and automatic WAL lock snapshot fallback. Never locks or alters the desktop client database.

• Hardware-Enforced Biometrics: All message sending operations are gated by native OS biometric prompts (macOS Touch ID / Windows Hello) with interactive recipient and text preview before dispatch.

• Flexible Message Dispatch:

  • auto: Focuses WhatsApp, stages the message, and automatically dispatches via native AppleScript Return keystroke.

  • draft: Opens the chat and stages the message text in the input box for manual human review and dispatch.

• Rich Media & Context Resolution: Inspects images, documents, PDFs, voice notes, and contact cards, resolving local filesystem paths and disk presence.

• Cross-Version CoreData Schema Adaptation: Automatically inspects table metadata at runtime to adapt across macOS Catalyst updates.

Related MCP server: WhatsApp MCP Server (TypeScript)

Architectural Overview

                      ┌────────────────────────────────┐
                      │    AI Agent / MCP Client       │
                      │  (Claude, Cursor, Antigravity) │
                      └───────────────┬────────────────┘
                                      │ stdio (JSON-RPC)
                                      ▼
                      ┌────────────────────────────────┐
                      │      WhatsApp MCP Server       │
                      └───────┬────────────────┬───────┘
                              │                │
            [Read-Only Layer] │                │ [Write Layer]
      (Zero-Friction SQLite)  │                │ (Biometric Guard)
                              ▼                ▼
            ┌───────────────────┐    ┌───────────────────┐
            │ ChatStorage.sqlite│    │ Native Biometrics │
            │ (mode=ro + WAL    │    │ (Touch ID / Hello)│
            │  snapshot safe)   │    └─────────┬─────────┘
            └───────────────────┘              │
                                               ▼
                                     ┌───────────────────┐
                                     │   WhatsApp.app    │
                                     │ (URL Scheme + UI) │
                                     └───────────────────┘

Prerequisites & Permissions

1. macOS Full Disk Access (FDA)

WhatsApp for macOS stores its SQLite database inside a sandboxed Group Container: ~/Library/Group Containers/group.net.whatsapp.WhatsApp.shared/ChatStorage.sqlite

To allow the MCP server (or your terminal / IDE) to read the database:

1. Open System Settings -> Privacy & Security -> Full Disk Access.

2. Click the + button.

3. Add your terminal application (e.g., Terminal, iTerm2, Ghostty) or your MCP client host (e.g., Cursor, VS Code, Antigravity) or Python executable.

4. Restart your terminal / IDE.

To verify access at any time, run:

whatsapp-mcp --status

Installation

Using uv (Recommended)

# Clone the repository
git clone https://github.com/hemelbesem90s/WhatsApp-MCP.git
cd WhatsApp-MCP

# Create environment and install
uv venv .venv --python 3.13
source .venv/bin/activate
uv pip install -e ".[dev]"

Using standard pip

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Configuration

Settings can be specified in a .env file or passed as environment variables:

MCP Tool Reference

Read Tools (Zero Friction, Read-Only)

Write Tools (Biometric-Gated)

Client Integration Examples

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "whatsapp": {
      "command": "/path/to/whatsapp-mcp/.venv/bin/whatsapp-mcp",
      "args": [],
      "env": {
        "WHATSAPP_MCP_ENABLE_WRITE_TOOLS": "true",
        "WHATSAPP_MCP_REQUIRE_BIOMETRIC": "true",
        "WHATSAPP_MCP_SEND_MODE": "auto"
      }
    }
  }
}

Antigravity / Gemini CLI (mcp_config.json)

{
  "mcpServers": {
    "whatsapp": {
      "command": "/path/to/whatsapp-mcp/.venv/bin/whatsapp-mcp",
      "args": [],
      "env": {
        "WHATSAPP_MCP_ENABLE_WRITE_TOOLS": "true",
        "WHATSAPP_MCP_REQUIRE_BIOMETRIC": "true",
        "WHATSAPP_MCP_SEND_MODE": "auto"
      }
    }
  }
}

Development & Testing

# Run unit test suite with coverage
make test

# Run linter
make lint

# Run type checker
make typecheck

# Full test and verification suite
make check

License

MIT License. See LICENSE for details.