Skip to main content
Glama
whatsapp-mcp-gateway

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
```