WhatsApp Web MCP Server

Package (npm 1.2.0)

npx -y [email protected]

Or add to your MCP client config:

{
  "mcpServers": {
    "mcp-whatsapp-web": {
      "command": "npx",
      "args": [
        "-y",
        "[email protected]"
      ],
      "env": {
        "WHATSAPP_BACKEND": "<YOUR_VALUE>",
        "BAILEYS_SESSION_DIR": "<YOUR_VALUE>",
        "LOG_LEVEL": "<YOUR_VALUE>",
        "LOG_STDERR_LEVEL": "<YOUR_VALUE>",
        "WHATSAPP_HEADLESS": "<YOUR_VALUE>",
        "WHATSAPP_NO_SANDBOX": "<YOUR_VALUE>",
        "BROWSER_EXECUTABLE_PATH": "<YOUR_VALUE>",
        "WHATSAPP_SESSION_DIR": "<YOUR_VALUE>",
        "WHATSAPP_PAIRING_PHONE_NUMBER": "<YOUR_VALUE>",
        "FFMPEG_PATH": "<YOUR_VALUE>",
        "WA_WEB_VERSION": "<YOUR_VALUE>",
        "HEALTH_CHECK_INTERVAL_MS": "<YOUR_VALUE>",
        "TOOL_READY_TIMEOUT_MS": "<YOUR_VALUE>",
        "MCP_HTTP_PORT": "<YOUR_VALUE>",
        "MCP_HTTP_HOST": "<YOUR_VALUE>",
        "MCP_OAUTH": "<YOUR_VALUE>"
      }
    }
  }
}

• WHATSAPP_BACKEND — WhatsApp backend: webjs uses a persistent browser profile; baileys connects without a browser and requires separate pairing
• BAILEYS_SESSION_DIR — Baileys credentials and synchronized history directory (default: <working directory>/baileys-sessions). Use a private absolute path, owned by one server process.
• LOG_LEVEL — Log level for the log file (logs/mcp-whatsapp.log)
• LOG_STDERR_LEVEL — Log level for stderr (visible in most MCP client logs)
• WHATSAPP_HEADLESS — webjs only: set to false to show the browser window instead of running headless
• WHATSAPP_NO_SANDBOX — webjs only: explicitly disable the browser sandbox for containers that require it. The sandbox is enabled by default.
• BROWSER_EXECUTABLE_PATH — webjs only: browser executable. Chrome and Edge are auto-detected; set this to use a specific browser. Chrome/Edge is required for sending videos and GIFs.
• WHATSAPP_SESSION_DIR — webjs only: persistent browser profile directory (default: <working directory>/whatsapp-sessions)
• WHATSAPP_PAIRING_PHONE_NUMBER — Phone number pairing: when set (international, symbol-free format, e.g. 4915112345678), an 8-character pairing code is logged to stderr on startup instead of relying on the QR code
• FFMPEG_PATH — Path to an ffmpeg binary (only needed to override the ffmpeg installed automatically via the ffmpeg-static npm package)
• WA_WEB_VERSION — webjs only: pin the WhatsApp Web version if a WhatsApp-side update breaks the client.
• HEALTH_CHECK_INTERVAL_MS — webjs only: connection health check interval in milliseconds (<=0 disables)
• TOOL_READY_TIMEOUT_MS — How long tool calls wait for the WhatsApp client to become ready before erroring
• MCP_HTTP_PORT — When set, additionally exposes the MCP endpoint at http://127.0.0.1:<port>/mcp (Streamable HTTP) from the same process
• MCP_HTTP_HOST — Bind address for the HTTP endpoint (do not expose publicly; the endpoint controls your personal WhatsApp account)
• MCP_OAUTH — Enable OAuth for the HTTP endpoint: /mcp requires a bearer token and clients authenticate via a browser page showing the WhatsApp QR code / pairing form