WhatsApp MCP Server

A local Python MCP server that automates WhatsApp Web through Playwright and exposes a small set of WhatsApp tools over stdio.

What this project does

• Runs as an MCP server over stdio.
• Uses Python instead of Node.
• Uses Playwright with Chromium.
• Persists the WhatsApp Web session under ./data/profile.

Current tools

• get_auth_status
• wait_until_ready
• list_recent_chats
• send_message
• get_recent_messages
• shutdown_browser

send_message and get_recent_messages accept either phone_number or chat_name. chat_name works by searching the existing WhatsApp sidebar/chat list. For larger get_recent_messages requests, the server attempts to scroll upward and load older visible history before extracting messages.

Important limitations

• This project automates WhatsApp Web, not the official WhatsApp Business API.
• WhatsApp Web markup changes regularly, so selectors may need maintenance.
• You should use a dedicated account and review WhatsApp's terms before production use.
• The repository is initialized as a Git repository on the main branch.

Recommended local setup

1. Copy the environment file:

cp .env.example .env

2. Create a virtual environment:

python3 -m venv .venv
source .venv/bin/activate

3. Install dependencies:

pip install -r requirements.txt
python3 -m playwright install chromium

4. For local login, set WHATSAPP_HEADLESS=false in .env.

5. Start the server locally:

PYTHONPATH=src python3 -m whatsapp_mcp.main

6. From your MCP client, call get_auth_status.

7. If a browser window opens, scan the QR code directly in that window.

8. Call wait_until_ready.

Example MCP client configuration

For Claude Desktop or another MCP client, local Python execution is the recommended configuration.

{
  "mcpServers": {
    "whatsapp": {
      "command": "/absolute/path/to/project/.venv/bin/python3",
      "args": [
        "-m",
        "whatsapp_mcp.main"
      ],
      "cwd": "/absolute/path/to/project",
      "env": {
        "PYTHONPATH": "/absolute/path/to/project/src",
        "WHATSAPP_HEADLESS": "false",
        "WHATSAPP_PROFILE_DIR": "/absolute/path/to/project/data/profile"
      }
    }
  }
}

Tool examples

get_auth_status

{
  "name": "get_auth_status",
  "arguments": {}
}

send_message

{
  "name": "send_message",
  "arguments": {
    "chat_name": "John Appleseed",
    "text": "Hello from the WhatsApp MCP server"
  }
}

get_recent_messages

{
  "name": "get_recent_messages",
  "arguments": {
    "chat_name": "John Appleseed",
    "count": 10
  }
}

Project structure

.
├── docs/
├── src/whatsapp_mcp/
├── .env.example
└── pyproject.toml

Documentation

• Usage guide
• Architecture notes