whatsapp-mcp-gateway
Provides a self-hosted, multi-session WhatsApp gateway with a connect tool for pairing WhatsApp sessions via QR code or phone-number pairing code. It maintains live WhatsApp connections, persists credentials in Postgres so sessions survive restarts, and supports independent sessions keyed by caller-supplied session IDs.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
whatsapp-mcp-gateway
A self-hosted, multi-session WhatsApp MCP gateway. It holds several live
WhatsApp connections in one process and exposes them to MCP clients over
Streamable HTTP (or stdio). Only the connect tool exists today.
Requirements
Node.js 26 (>=26.13 <27)
pnpm 12
Postgres 15 or newer. A
compose.yamlwith Postgres 17 is included for local development.
Related MCP server: whatsapp-mcp
Quickstart
pnpm install
docker compose up -d postgres
cp .env.example .env
# edit .env and set MCP_AUTH_TOKEN to a random value of at least 32 characters
pnpm db:migrate
pnpm build
pnpm startThe gateway listens on 0.0.0.0:8080 by default. Health is available at
GET /healthz; the MCP endpoint is POST /mcp.
If something else already uses port 5432 on your host, change the Postgres
port mapping in compose.yaml and the matching port in DATABASE_URL.
Configuration
Variable | Default | Notes |
| required | Postgres connection string |
|
|
|
|
| HTTP bind address |
|
| HTTP port |
| required for HTTP | At least 32 characters |
|
| pino level |
| unset | Enables LangSmith tracing when set |
|
| Explicit |
|
| LangSmith project name |
The HTTP transport refuses to start without MCP_AUTH_TOKEN, even on
loopback: the endpoint controls WhatsApp accounts, so there is no
unauthenticated mode. DATABASE_URL is always required.
Pairing a session
Call the connect tool with a caller-supplied sessionId:
{ "sessionId": "support-agent-1" }Without
phoneNumber, the result containsqr(the raw payload) and a text message with an ASCII QR code to scan.With
phoneNumber(7–15 digits), the result containspairingCodeto enter on the phone instead of scanning.The call returns promptly. The WhatsApp socket keeps connecting in the background, and later calls for the same session return its current state.
Credentials are stored in Postgres, so restarting the process does not require pairing again.
If WhatsApp logs the session out, its stored credentials are cleared and the session must be paired again.
Sessions are independent: different sessionId values get separate sockets,
and concurrent calls for different sessions do not block each other.
Concurrent calls for the same session share one connection attempt.
Remote MCP client
Point the client at http://<host>:8080/mcp and send:
Authorization: Bearer <MCP_AUTH_TOKEN>The gateway speaks plain HTTP. Terminate TLS in front of it (reverse proxy or load balancer) before exposing it beyond a trusted network.
Claude Desktop (stdio option)
Local clients that spawn processes can use stdio instead of HTTP:
{
"mcpServers": {
"whatsapp": {
"command": "node",
"args": ["/absolute/path/to/whatsapp-mcp-gateway/build/main.js"],
"env": {
"MCP_TRANSPORT": "stdio",
"DATABASE_URL": "postgres://gateway:gateway@localhost:5432/gateway"
}
}
}
}MCP_AUTH_TOKEN is not used for stdio. Logs go to stderr so stdio output
stays clean.
Security
MCP_AUTH_TOKENis one shared bearer token, not per-user authentication. Anyone holding it can control every WhatsApp session the gateway manages.Stored auth state is as sensitive as a logged-in WhatsApp session. Protect the Postgres database and its backups accordingly.
QR payloads, pairing codes, phone numbers, and credentials are returned only in tool results; they are never logged at
infoor below.Baileys is an unofficial WhatsApp client. Using it carries account-risk inherent to unofficial clients.
Run one gateway replica per session id. Sockets are not shared across processes; operators running multiple replicas must route a session id to a single replica.
Development
pnpm test # vitest unit tests (PGlite-backed, no network)
pnpm lint # oxlint
pnpm format:check # oxfmt
pnpm check-types # tsc --noEmit
pnpm db:generate # regenerate Drizzle migrations after schema changes
pnpm db:migrate # apply migrationsTool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Hosted WhatsApp MCP server: send and read messages from your own linked number. OAuth sign-in.
1Drive WhatsApp from any MCP client: pair devices, send text and media, manage contacts and groups.
Hosted WhatsApp MCP server: read, search and reply to your own WhatsApp chats from your AI.
WhatsMCP connects Claude and other MCP-compatible AI agents directly to WhatsApp. Send and receive text, images, documents, and voice notes; manage groups (create, add/remove members, promote admins); look up contacts and profiles; follow channels; and read call and message history — all through a standard MCP interface. For voice use cases, WhatsMCP offers SIP-based calling plans (inbound-only, or full inbound/outbound) so AI voice agents can answer and place WhatsApp calls, plus low-latency WebSocket integrations with voice agent providers like ElevenLabs. Multiple WhatsApp accounts can be paired and managed per workspace, with webhook support for real-time inbound message delivery to your own infrastructure.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients to send and read WhatsApp messages, download media, and inspect chats, groups, and session status through the waxum REST API gateway over stdio or Streamable HTTP.MIT
- AlicenseNot gradedqualityBmaintenanceEnables agents to use a personal WhatsApp account over MCP, with tools for messaging, real-time presence streams, and webhook subscriptions via a long-lived Docker daemon.MIT
- AlicenseNot gradedqualityBmaintenanceExposes each authenticated WhatsApp Web session on a Windows PC as a stateless Streamable HTTP MCP endpoint, letting MCP clients list chats, read and search messages, fetch profiles, and send text messages under per-session read-only or read-and-send permissions.MIT
- AlicenseNot gradedqualityBmaintenanceRuns locally and pairs an existing WhatsApp account as a linked device, enabling Claude Code, Codex, and other MCP clients to read chats, retrieve media, draft replies, and send messages only after client-enforced human approval.49 npmMIT