WhatsApp Web MCP Server MCP Server

Name: WhatsApp Web MCP Server MCP Server
Author: io.github.mario-andreschak

io.github.mario-andreschak/mcp-whatsapp-web

Repository Registry

What is the WhatsApp Web MCP Server MCP server?

MCP server for WhatsApp via whatsapp-web.js: send/receive messages, media, chats, groups, contacts

How to install WhatsApp Web MCP Server

Copy-paste configuration for popular MCP clients.

transport: stdio

Config generated by PluginBench — verify against the source before use.

Environment / auth

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
Set to false to show the browser window instead of running headless (debugging aid)
BROWSER_EXECUTABLE_PATH
Browser executable. Chrome and Edge are auto-detected in their standard install locations; set this only to use a specific browser. A real Chrome/Edge is required for sending videos and GIFs.
WHATSAPP_SESSION_DIR
Where the WhatsApp session (browser profile) is stored (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
Pin the WhatsApp Web version. Only set this if a WhatsApp-side update breaks the client.
HEALTH_CHECK_INTERVAL_MS
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

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mcp-whatsapp-web": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-whatsapp-web"
      ],
      "env": {
        "LOG_LEVEL": "<YOUR_LOG_LEVEL>",
        "LOG_STDERR_LEVEL": "<YOUR_LOG_STDERR_LEVEL>",
        "WHATSAPP_HEADLESS": "<YOUR_WHATSAPP_HEADLESS>",
        "BROWSER_EXECUTABLE_PATH": "<YOUR_BROWSER_EXECUTABLE_PATH>",
        "WHATSAPP_SESSION_DIR": "<YOUR_WHATSAPP_SESSION_DIR>",
        "WHATSAPP_PAIRING_PHONE_NUMBER": "<YOUR_WHATSAPP_PAIRING_PHONE_NUMBER>",
        "FFMPEG_PATH": "<YOUR_FFMPEG_PATH>",
        "WA_WEB_VERSION": "<YOUR_WA_WEB_VERSION>",
        "HEALTH_CHECK_INTERVAL_MS": "<YOUR_HEALTH_CHECK_INTERVAL_MS>",
        "TOOL_READY_TIMEOUT_MS": "<YOUR_TOOL_READY_TIMEOUT_MS>",
        "MCP_HTTP_PORT": "<YOUR_MCP_HTTP_PORT>",
        "MCP_HTTP_HOST": "<YOUR_MCP_HTTP_HOST>",
        "MCP_OAUTH": "<YOUR_MCP_OAUTH>"
      }
    }
  }
}

Cursor

~/.cursor/mcp.json

{
  "mcpServers": {
    "mcp-whatsapp-web": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-whatsapp-web"
      ],
      "env": {
        "LOG_LEVEL": "<YOUR_LOG_LEVEL>",
        "LOG_STDERR_LEVEL": "<YOUR_LOG_STDERR_LEVEL>",
        "WHATSAPP_HEADLESS": "<YOUR_WHATSAPP_HEADLESS>",
        "BROWSER_EXECUTABLE_PATH": "<YOUR_BROWSER_EXECUTABLE_PATH>",
        "WHATSAPP_SESSION_DIR": "<YOUR_WHATSAPP_SESSION_DIR>",
        "WHATSAPP_PAIRING_PHONE_NUMBER": "<YOUR_WHATSAPP_PAIRING_PHONE_NUMBER>",
        "FFMPEG_PATH": "<YOUR_FFMPEG_PATH>",
        "WA_WEB_VERSION": "<YOUR_WA_WEB_VERSION>",
        "HEALTH_CHECK_INTERVAL_MS": "<YOUR_HEALTH_CHECK_INTERVAL_MS>",
        "TOOL_READY_TIMEOUT_MS": "<YOUR_TOOL_READY_TIMEOUT_MS>",
        "MCP_HTTP_PORT": "<YOUR_MCP_HTTP_PORT>",
        "MCP_HTTP_HOST": "<YOUR_MCP_HTTP_HOST>",
        "MCP_OAUTH": "<YOUR_MCP_OAUTH>"
      }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mcp-whatsapp-web": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-whatsapp-web"
      ],
      "env": {
        "LOG_LEVEL": "<YOUR_LOG_LEVEL>",
        "LOG_STDERR_LEVEL": "<YOUR_LOG_STDERR_LEVEL>",
        "WHATSAPP_HEADLESS": "<YOUR_WHATSAPP_HEADLESS>",
        "BROWSER_EXECUTABLE_PATH": "<YOUR_BROWSER_EXECUTABLE_PATH>",
        "WHATSAPP_SESSION_DIR": "<YOUR_WHATSAPP_SESSION_DIR>",
        "WHATSAPP_PAIRING_PHONE_NUMBER": "<YOUR_WHATSAPP_PAIRING_PHONE_NUMBER>",
        "FFMPEG_PATH": "<YOUR_FFMPEG_PATH>",
        "WA_WEB_VERSION": "<YOUR_WA_WEB_VERSION>",
        "HEALTH_CHECK_INTERVAL_MS": "<YOUR_HEALTH_CHECK_INTERVAL_MS>",
        "TOOL_READY_TIMEOUT_MS": "<YOUR_TOOL_READY_TIMEOUT_MS>",
        "MCP_HTTP_PORT": "<YOUR_MCP_HTTP_PORT>",
        "MCP_HTTP_HOST": "<YOUR_MCP_HTTP_HOST>",
        "MCP_OAUTH": "<YOUR_MCP_OAUTH>"
      }
    }
  }
}

VS Code

.vscode/mcp.json

{
  "servers": {
    "mcp-whatsapp-web": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mcp-whatsapp-web"
      ],
      "env": {
        "LOG_LEVEL": "<YOUR_LOG_LEVEL>",
        "LOG_STDERR_LEVEL": "<YOUR_LOG_STDERR_LEVEL>",
        "WHATSAPP_HEADLESS": "<YOUR_WHATSAPP_HEADLESS>",
        "BROWSER_EXECUTABLE_PATH": "<YOUR_BROWSER_EXECUTABLE_PATH>",
        "WHATSAPP_SESSION_DIR": "<YOUR_WHATSAPP_SESSION_DIR>",
        "WHATSAPP_PAIRING_PHONE_NUMBER": "<YOUR_WHATSAPP_PAIRING_PHONE_NUMBER>",
        "FFMPEG_PATH": "<YOUR_FFMPEG_PATH>",
        "WA_WEB_VERSION": "<YOUR_WA_WEB_VERSION>",
        "HEALTH_CHECK_INTERVAL_MS": "<YOUR_HEALTH_CHECK_INTERVAL_MS>",
        "TOOL_READY_TIMEOUT_MS": "<YOUR_TOOL_READY_TIMEOUT_MS>",
        "MCP_HTTP_PORT": "<YOUR_MCP_HTTP_PORT>",
        "MCP_HTTP_HOST": "<YOUR_MCP_HTTP_HOST>",
        "MCP_OAUTH": "<YOUR_MCP_OAUTH>"
      }
    }
  }
}

Claude Code

claude mcp add mcp-whatsapp-web --env LOG_LEVEL=<YOUR_LOG_LEVEL> --env LOG_STDERR_LEVEL=<YOUR_LOG_STDERR_LEVEL> --env WHATSAPP_HEADLESS=<YOUR_WHATSAPP_HEADLESS> --env BROWSER_EXECUTABLE_PATH=<YOUR_BROWSER_EXECUTABLE_PATH> --env WHATSAPP_SESSION_DIR=<YOUR_WHATSAPP_SESSION_DIR> --env WHATSAPP_PAIRING_PHONE_NUMBER=<YOUR_WHATSAPP_PAIRING_PHONE_NUMBER> --env FFMPEG_PATH=<YOUR_FFMPEG_PATH> --env WA_WEB_VERSION=<YOUR_WA_WEB_VERSION> --env HEALTH_CHECK_INTERVAL_MS=<YOUR_HEALTH_CHECK_INTERVAL_MS> --env TOOL_READY_TIMEOUT_MS=<YOUR_TOOL_READY_TIMEOUT_MS> --env MCP_HTTP_PORT=<YOUR_MCP_HTTP_PORT> --env MCP_HTTP_HOST=<YOUR_MCP_HTTP_HOST> --env MCP_OAUTH=<YOUR_MCP_OAUTH> -- npx -y mcp-whatsapp-web