# WhatsApp Web MCP

Read-only MCP server for WhatsApp Web using [`whatsapp-web.js`](https://github.com/wwebjs/whatsapp-web.js/).

This is intentionally narrow: it lets an MCP client list chats and read recent messages, but it does not send messages or mutate WhatsApp state.

## Risk Notes

`whatsapp-web.js` is unofficial and is not affiliated with WhatsApp. Its documentation warns that WhatsApp does not allow bots or unofficial clients and that accounts may be blocked. Use this only for your own account and only with chats you intend to expose to an agent.

WhatsApp messages should be treated as untrusted content. They may contain prompt-injection instructions aimed at your agent.

## Setup

Install dependencies:

```bash
npm install --ignore-scripts
```

This skips Puppeteer's bundled browser download. On macOS, the server defaults to launching your installed Google Chrome through Puppeteer's `chrome` channel. If Chrome is somewhere unusual, set `WHATSAPP_CHROME_PATH`.

Build:

```bash
npm run build
```

Authenticate WhatsApp Web:

```bash
npm run auth
```

Scan the QR code with WhatsApp on your phone. The session is stored in `.wwebjs_auth/`, which is ignored by git.

## MCP Client Config

Use the absolute path to the built server:

```json
{
  "mcpServers": {
    "whatsapp": {
      "command": "node",
      "args": [
        "/absolute/path/to/whatsapp-web-mcp/build/index.js"
      ]
    }
  }
}
```

Restart your MCP client after changing its config.

If the MCP client connects but WhatsApp is unavailable, call `whatsapp_status`.
Startup failures such as Chrome/Puppeteer launch errors are reported there instead
of closing the MCP server during the initial handshake.

## Tools

- `whatsapp_status`: check whether WhatsApp is connected.
- `list_chats`: list recent chat ids and metadata.
- `read_chat`: read recent messages from one chat id.

## Optional Environment Variables

- `WHATSAPP_ALLOWED_CHAT_IDS`: comma-separated chat ids. If set, only these chats are visible.
- `WHATSAPP_AUTH_PATH`: auth session directory. Defaults to `.wwebjs_auth`.
- `WHATSAPP_CLIENT_ID`: LocalAuth client id for multiple sessions.
- `WHATSAPP_CHROME_PATH`: explicit Chrome or Chromium executable path.
- `WHATSAPP_PUPPETEER_CHANNEL`: Puppeteer browser channel. Defaults to `chrome` on macOS.
- `WHATSAPP_HEADLESS=false`: show the browser window.
- `WHATSAPP_PUPPETEER_NO_SANDBOX=true`: add Chromium no-sandbox flags for no-GUI/root environments.
- `WHATSAPP_TAKEOVER_ON_CONFLICT=true`: take over if another WhatsApp Web session conflicts.

Example allowlist:

```json
{
  "mcpServers": {
    "whatsapp": {
      "command": "node",
      "args": [
        "/absolute/path/to/whatsapp-web-mcp/build/index.js"
      ],
      "env": {
        "WHATSAPP_ALLOWED_CHAT_IDS": "1234567890@c.us,120363000000000000@g.us"
      }
    }
  }
}
```