WhatsApp Web MCP

Read-only MCP server for WhatsApp Web using 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:

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:

npm run build

Authenticate WhatsApp Web:

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:

{
  "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:

{
  "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"
      }
    }
  }
}