whatsapp-mcp-gateway
by alinrajpoot
README.md
# 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.
## Quickstart
```bash
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`:
```json
{ "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:
```json
{
"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
```bash
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
```