WhatsApp MCP Server for Poke

A self-hosted Model Context Protocol (MCP) server that bridges WhatsApp Web to Poke via Server-Sent Events (SSE).

Architecture

WhatsApp Web  ──(Puppeteer)──▶  whatsapp-web.js
                                      │
                                 WhatsAppManager
                                      │
                              MCP Tools (4 tools)
                                      │
                            Express SSE Transport
                                      │
                              http://localhost:3000/sse
                                      │
                                  ◀── Poke ──▶

Stack: Node.js · TypeScript · @modelcontextprotocol/sdk · whatsapp-web.js · Puppeteer · Docker

Related MCP server: WhatsApp MCP

Quick Start

1. Clone and build

git clone <your-repo>
cd whatsapp-mcp-server
docker compose up --build

2. Scan the QR code

Watch the container logs for a terminal QR code:

docker compose logs -f

Open WhatsApp on your phone → Linked Devices → Link a Device → scan the QR.

The session is saved in a Docker volume (whatsapp_session) and persists across restarts.

3. Verify the server is ready

curl http://localhost:3000/health
# {"status":"ok","whatsapp":{"ready":true,"qrPending":false}}

4. Register in Poke

1. Go to https://poke.com/integrations/new

2. Choose MCP / SSE integration

3. Enter the SSE URL:

   http://<your-server-ip>:3000/sse

4. Save. Poke will open the SSE stream and discover all four tools automatically.

MCP Tools

Recipient ID format

send_message accepts either:

• Full serialized ID: 923001234567@c.us

• Plain international number: 923001234567

Endpoints

Configuration

Set via environment variables or edit docker-compose.yml:

Session Persistence

The WhatsApp session is stored in a named Docker volume:

volumes:
  whatsapp_session:
    driver: local

To back it up:

docker run --rm \
  -v whatsapp-mcp-server_whatsapp_session:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/session-backup.tar.gz -C /data .

To restore:

docker run --rm \
  -v whatsapp-mcp-server_whatsapp_session:/data \
  -v $(pwd):/backup \
  alpine tar xzf /backup/session-backup.tar.gz -C /data

Production Tips

• Reverse proxy: Put Nginx/Caddy in front with HTTPS so Poke connects over https://yourdomain.com/sse

• Firewall: Only expose port 3000 to trusted IPs or hide behind a reverse proxy

• Logs: docker compose logs -f whatsapp-mcp — structured JSON logs rotated at 10 MB × 3 files

• Re-authentication: If WhatsApp logs out, delete the session volume and restart to get a fresh QR

Troubleshooting

Container crashes with error while loading shared libraries: libnss3.so → The Dockerfile installs libnss3 automatically. Rebuild: docker compose build --no-cache

QR not appearing in logs → docker compose logs -f — give it 30–60 s to start Chromium

WhatsApp client is not ready → Hit /health to check status, then /qr to retrieve the current QR if pending

Poke can't reach the SSE URL → Make sure port 3000 is accessible from Poke's servers (check firewall / security groups)