# 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:

```bash
cp .env.example .env
```

2. Create a virtual environment:

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

3. Install dependencies:

```bash
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:

```bash
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.

```json
{
  "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`

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

### `send_message`

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

### `get_recent_messages`

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

## Project structure

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

## Documentation

- [Usage guide](./docs/USAGE.md)
- [Architecture notes](./docs/ARCHITECTURE.md)