Skip to main content
Glama
whatsapp-mcp-gateway

whatsapp-mcp-gateway

by alinrajpoot

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.yaml with 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 start

The 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

DATABASE_URL

required

Postgres connection string

MCP_TRANSPORT

http

http or stdio

MCP_HOST

0.0.0.0

HTTP bind address

MCP_PORT

8080

HTTP port

MCP_AUTH_TOKEN

required for HTTP

At least 32 characters

LOG_LEVEL

info

pino level

LANGSMITH_API_KEY

unset

Enables LangSmith tracing when set

LANGSMITH_TRACING

true when a key is set

Explicit false disables tracing

LANGSMITH_PROJECT

whatsapp-mcp-gateway

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 contains qr (the raw payload) and a text message with an ASCII QR code to scan.

  • With phoneNumber (7–15 digits), the result contains pairingCode to 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_TOKEN is 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 info or 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 migrations

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      B
      maintenance
      Exposes 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
    • A
      license
      Not graded
      quality
      B
      maintenance
      Runs 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 npm
      MIT