mcp-whatsapp-web

WhatsApp Web MCP Server

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

stdiocommunityservice

Package Details

mcp-whatsapp-web

1.1.0•https://www.npmjs.com/package/mcp-whatsapp-web

Transportstdio

Runtimenpx

Environment Variables

LOG_LEVEL(str)

Default:info

Log level for the log file (logs/mcp-whatsapp.log)

LOG_STDERR_LEVEL(str)

Default:warn

Log level for stderr (visible in most MCP client logs)

WHATSAPP_HEADLESS(bool)

Set to false to show the browser window instead of running headless (debugging aid)

BROWSER_EXECUTABLE_PATH(file)

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(file)

Where the WhatsApp session (browser profile) is stored (default: <working directory>/whatsapp-sessions)

WHATSAPP_PAIRING_PHONE_NUMBER(str)

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(file)

Path to an ffmpeg binary (only needed to override the ffmpeg installed automatically via the ffmpeg-static npm package)

WA_WEB_VERSION(str)

Pin the WhatsApp Web version. Only set this if a WhatsApp-side update breaks the client.

HEALTH_CHECK_INTERVAL_MS(num)

Default:60000

Connection health check interval in milliseconds (<=0 disables)

TOOL_READY_TIMEOUT_MS(num)

Default:45000

How long tool calls wait for the WhatsApp client to become ready before erroring

MCP_HTTP_PORT(num)

When set, additionally exposes the MCP endpoint at http://127.0.0.1:<port>/mcp (Streamable HTTP) from the same process

MCP_HTTP_HOST(str)

Default:127.0.0.1

Bind address for the HTTP endpoint (do not expose publicly; the endpoint controls your personal WhatsApp account)

MCP_OAUTH(bool)

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