WACrew

Guide

Run a WhatsApp MCP server in Docker

How to run a WhatsApp MCP server in Docker so it stays online 24/7: WACrew, whatsapp-mcp-extended and whatzmcp, with the volume that keeps your session and the way your MCP client connects.

Updated 2 min read
On this page
  1. What has to persist
  2. WACrew
  3. whatsapp-mcp-extended
  4. whatzmcp
  5. Choosing a pattern
  6. Security checklist
  7. FAQ

A WhatsApp MCP server only sees messages that arrive while its session is online. On a laptop that sleeps, history gets holes. Docker on a small VPS fixes that, and keeps the setup reproducible. Three projects ship Docker support today.

What has to persist

Whatever the project, mount a volume for two things:

  1. The WhatsApp session (auth keys). Lose it and you scan the QR code again.
  2. The message store (SQLite or files) and downloaded media.

WACrew

The repository has a Dockerfile, a docker-compose.yml and a prebuilt image at ghcr.io/sumioshi/wacrew.

git clone https://github.com/sumioshi/wacrew && cd wacrew
cp .env.example .env   # set PANEL_USER and PANEL_PASS
docker compose up -d

The container runs the collector and the web panel on port 3000, with data in a volume at /data. Scan the QR code at /config. Your MCP client does not run in Docker; it runs npx -y wacrew-mcp locally and talks to the panel over HTTPS with WAC_CLOUD_URL, WAC_CLOUD_USER and WAC_CLOUD_PASS. Without PANEL_USER and PANEL_PASS the panel is open, which is only acceptable on localhost.

Prefer not to manage a server? The Railway template sets up the volume, login and a generated password.

whatsapp-mcp-extended

FelixIsaac/whatsapp-mcp-extended runs the lharries-style Go bridge (port 8080), the Python MCP server (8081) and a small web UI (8090) with docker compose. Its README creates an external Docker network first, then docker-compose up -d, and you read the QR code from docker-compose logs -f whatsapp-bridge. The MCP client config still points uv at the server folder.

whatzmcp

whatzmcp publishes ghcr.io/whatzmcp/whatzmcp. You link once interactively, then use docker run -i as the command in your MCP client, so the container is started by the client over stdio:

docker run -it --rm -v whatzmcp-data:/data ghcr.io/whatzmcp/whatzmcp login
docker run -i --rm -v whatzmcp-data:/data ghcr.io/whatzmcp/whatzmcp

That keeps your machine clean, but the session is only online while the client runs it.

Choosing a pattern

PatternAlways onlineExample
Long-running container on a server, MCP connects remotelyYesWACrew, whatsapp-mcp-extended
Container started by the MCP client over stdioOnly while the client runswhatzmcp

Security checklist

  • Put HTTPS and a login in front of any panel or HTTP endpoint.
  • Never commit the session folder or .env.
  • Back up the volume; it holds your messages.
  • Restrict who can send. In WACrew, chats start in Confirm mode; whatsapp-mcp-extended has an allowlist (WHATSAPP_ALLOWLIST_JIDS).

FAQ

How much server do I need? A small VPS is enough for one number. Transcription on the server uses an API backend (TRANSCRIBE_BACKEND=openrouter in WACrew) unless you have a GPU.

Can I run several numbers? Each WACrew deployment holds one WhatsApp session, so run one container (and volume) per number.

Does Docker reduce ban risk? No. Risk depends on how the account is used, not where the session runs.