# WhatsApp MCP Server

A **local stdio-only** MCP server for a personal WhatsApp account using WhatsApp Web QR pairing. It provides chat and media reading plus **safe opt-in** text and media sending. Outbound tools are disabled unless explicitly enabled and limited to an allowlisted set of chats.

> **Risk:** this uses an unofficial WhatsApp Web library. WhatsApp may change its protocol or restrict accounts that use unofficial clients. Use only with your own account, keep session state private, and prefer a separate account for experimentation.

## Install

```bash
npm install
cp .env.example .env
npm run build
```

Set `WHATSAPP_ALLOWLIST` in `.env` to comma-separated WhatsApp JIDs. It is required for `send_message` and `send_media`; read tools remain available with an empty allowlist. Keep outbound files in `WHATSAPP_OUTBOUND_MEDIA_DIRS` (default: `./outbox`).

## Pair

```bash
npm start
```

On first launch the server writes `whatsapp-qr.png` locally with mode `0600`. Scan it from WhatsApp: **Linked devices → Link a device**. The local auth directory and media directories are created with mode `0700`.

The process speaks MCP over **stdin/stdout**. Status and errors use stderr only. Do not expose this process behind HTTP or a network socket.

## MCP tools

- `connection_status` — pairing/connection state and local QR location
- `list_chats` — cached chats
- `search_messages` — text search over the local session cache
- `read_messages` — recent cached messages for an allowlisted chat
- `download_media` — save a cached allowlisted message attachment locally
- `fetch_all_chats` — list every chat in the local session cache
- `fetch_message_history` — page older messages for an allowlisted chat via Baileys `fetchMessageHistory`
- `send_message` — send text to an allowlisted chat (**requires `WHATSAPP_SENDING_ENABLED=true`**)
- `send_media` — send an image, video, audio, document, or sticker from an approved local file (**requires `WHATSAPP_SENDING_ENABLED=true`**)

The cache starts filling after WhatsApp history/message events arrive. It is intentionally not a full archive. `fetch_message_history` can pull older messages on demand, but only while the WhatsApp socket is connected.

## MCP client configuration

```json
{
  "mcpServers": {
    "whatsapp-local": {
      "command": "node",
      "args": ["/absolute/path/to/whatsapp-mcp-server/dist/index.js"],
      "env": {
        "WHATSAPP_ALLOWLIST": "1234567890@s.whatsapp.net",
        "WHATSAPP_SENDING_ENABLED": "true",
        "WHATSAPP_OUTBOUND_MEDIA_DIRS": "/absolute/path/to/whatsapp-mcp-server/outbox"
      }
    }
  }
}
```

## Safety controls

- Stdio transport only; no HTTP listener.
- Sending is disabled by default. `send_message` and `send_media` require `WHATSAPP_SENDING_ENABLED=true` **and** a non-empty `WHATSAPP_ALLOWLIST`.
- Send tools are gated at call time, so a config typo cannot silently enable them.
- Outbound media must resolve to a regular file within `WHATSAPP_OUTBOUND_MEDIA_DIRS` and stay below `WHATSAPP_MAX_OUTBOUND_MEDIA_BYTES` (64 MiB default).
- Outbound sends have a separate rate limit (default: 10/minute) independent of read limits.
- Input validation via Zod on every tool.
- Per-process read rate limit (default: 30 tool calls/minute).
- Result caps (default: 50) and local allowlist support.
- Auth files, QR image, downloaded media, outbound files, `.env`, build output, and logs are gitignored.
- Sensitive files/directories are written with `0600`/`0700` modes where created by this service.

## Verify

```bash
npm run check
npm test
```

## License

MIT. See [LICENSE](LICENSE).

## Viewing the QR code

The QR image is written to the local `whatsapp-qr.png` path. Attach or upload that image in your MCP client UI after launching the server. The QR expires quickly; call `connection_status` after scanning to confirm the connection state is `connected`.
# Whatsapp-Mcp