GoWA MCP Server

Go WhatsApp — Built for Efficient Memory Use

If you're using this tool to generate income, consider supporting its development by becoming a Patreon member!

Your support helps ensure the project stays maintained and receives regular updates!

Related MCP server: WhatsApp Cloud API MCP Server

ARM, AMD64, and MCP Support

Download:

• Release

• Docker Hub

• GitHub Container Registry

n8n Community Node

• n8n package

• Go to Settings → Community Nodes, enter @dresar/n8n-nodes-gowa, and select Install.

Breaking Changes

• v6

  • REST mode requires <binary> rest instead of <binary>.

    • Example: ./whatsapp rest instead of ./whatsapp.

  • MCP mode required <binary> mcp.

    • Example: ./whatsapp mcp.

• v7

  • Starting with version 7.x, binaries are built with GoReleaser and can be downloaded from the latest release.

• v8

  • Multi-device support: You can now connect and manage multiple WhatsApp accounts simultaneously in a single server instance.

  • New Device Management API: New endpoints under /devices manage multiple devices.

  • Device scoping required: All device-scoped REST API calls now require either:

    • X-Device-Id header, or

    • device_id query parameter.

    • If only one device is registered, it is used as the default.

  • WebSocket device scoping: Connect to /ws?device_id=<id> to scope the WebSocket connection to a specific device.

  • Remote UI support: CORS allows the Authorization and X-Device-Id headers, so a standalone web UI (for example, gowa-ui) hosted on another origin can call the API directly. GET /app/info exposes the version and media size limits. Because browsers cannot set headers on WebSocket connections, pass /ws?device_id=<id>&authorization=<base64(user:pass)> when Basic Auth is enabled (use TLS—the credential is visible in the URL).

  • Webhook payload changes: All webhook payloads now include a top-level device_id field identifying which device received the event:

    {
      "event": "message",
      "device_id": "628123456789@s.whatsapp.net",
      "payload": { ... }
    }

• v9

  • MCP and API are unified under rest: MCP is no longer a separate mode or process. Run ./whatsapp rest to serve both the REST API and MCP; MCP is available at /mcp (no standalone mcp subcommand). See MCP Server (Model Context Protocol) for migration details.

  • UI moved to a separate repository: The web dashboard is no longer bundled in this repo. It now lives at dresar/gowa-ui and ships as a single self-contained gowa-ui.html. The server downloads the latest dashboard release at startup, verifies its SHA-256 digest, caches it under storages/ui/, and serves it at /. See Web dashboard (gowa-ui) for the APP_UI_* settings, supply-chain pinning, and air-gapped deployment.

Features

• Send WhatsApp messages through the HTTP API. See docs/openapi.yaml for details.

• MCP (Model Context Protocol) server support — Integrate with AI agents and tools using a standardized protocol.

• Optional MCP OAuth 2.1 — Connect remote MCP clients that cannot supply a Basic Auth header. See MCP OAuth.

• Mention users in message text and image, video, or file captions:

  • @phoneNumber

  • Example: Hello @628974812XXXX, @628974812XXXX

• Ghost mentions (mention all) — Mention group participants without showing @phone in the message text.

  • Pass phone numbers in the mentions field to mention users without a visible @ in the message.

  • Use the special keyword @everyone to automatically mention all group participants.

• Post WhatsApp status updates.

• Mark incoming audio messages and voice notes as played.

• Scheduled sends — Send any message later, once or on a daily, weekly, or monthly repeat.

  • Add scheduled_at (RFC3339) and timezone (IANA) to a send request; recurrence, weekdays, day_of_month, end_at, and occurrence_limit control repeats.

  • Schedules survive restarts and wait for an offline device; list, pause, resume, or cancel them at /send/schedules.

• Send stickers — Automatically convert images to WebP sticker format.

  • Supports JPG, JPEG, PNG, WebP, and GIF formats.

  • Automatically resizes images to 512×512 pixels.

  • Preserves transparency in PNG images.

  • Animated WebP stickers are supported but must meet WhatsApp requirements:

    • Exactly 512×512 pixels.

    • Less than 500 KB.

    • No more than 10 seconds long.

    • If an animated sticker does not meet these requirements, resize it before uploading with a tool such as ezgif.com.

• Compress images before sending.

• Compress videos before sending.

• Customize the OS name shown as the linked device name in WhatsApp:

  • --os=Chrome or --os=MyApplication

• Basic Auth with multiple credentials:

  • --basic-auth=kemal:secret,toni:password,userName:secretPassword

  • Short form: -b=kemal:secret,toni:password,userName:secretPassword

• Subpath deployment support:

  • --base-path="/gowa" allows deployment under a path such as /gowa.

• Customizable port and debug mode:

  • --port 8000

  • --debug true

• Automatic replies to incoming messages:

  • --autoreply="Don't reply to this message"

• Automatically mark incoming messages as read:

  • --auto-mark-read=true

• Automatically download media from incoming messages:

  • --auto-download-media=false disables automatic media downloads (default: true).

• Ignore downloading status media:

  • --ignore-status-media=true disables downloading status media (default: false).

• Automatically reject incoming calls:

  • --auto-reject-call=true or WHATSAPP_AUTO_REJECT_CALL=true (see Webhook Payload for call events).

• Configurable presence on connect:

  • --presence-on-connect=unavailable or WHATSAPP_PRESENCE_ON_CONNECT=unavailable

  • available — Mark the account as online (suppresses phone notifications).

  • unavailable — Register the push name without going online (default; preserves phone notifications).

  • none — Skip presence entirely (the push name is not registered, so contacts may see - as the name).

• Daily presence pulse:

  • --presence-pulse-enabled=true or WHATSAPP_PRESENCE_PULSE_ENABLED=true (default: true).

  • --presence-pulse-interval=24h controls how often each connected device is pulsed.

  • --presence-pulse-duration=5m controls how long the account stays available before returning to unavailable.

• Webhooks for received messages and other events:

  • --webhook="http://yourwebhook.site/handler"

  • Short form: -w="http://yourwebhook.site/handler"

  • See Webhook Payload Documentation for details.

• Per-device webhooks — Each device can have its own webhook URL and event filters.

  • Set via API: PATCH /devices/:device_id/webhook with {"webhook_url": "https://device-webhook.site/handler"}.

  • Get via API: GET /devices/:device_id/webhook.

  • When a device has a custom webhook, events for that device are sent to the device-specific URL.

  • When no device webhook is set, events fall back to the global webhook (--webhook).

  • Set webhook_url to an empty string with PATCH to clear it and use the global webhook.

  • Set WHATSAPP_WEBHOOK_DEVICE_MERGE_GLOBAL=true (or --webhook-device-merge-global=true) to make a device webhook an addition instead of a replacement: the global --webhook URLs still receive the device's events (signed with the global secret, filtered by WHATSAPP_WEBHOOK_EVENTS) while the device URL keeps its own secret and event filter.

• Webhook signatures — Webhook requests include an HMAC-SHA-256 signature in the X-Hub-Signature-256 header, generated with the default key secret.

  Change the key with:

  • --webhook-secret="secret"

• Webhook payload documentation — For detailed schemas, security implementation, and integration examples, see Webhook Payload Documentation.

• Webhook event filtering — Filter which events are forwarded to your webhook with:

  • --webhook-events="message,message.ack" (a comma-separated list), or

  • WHATSAPP_WEBHOOK_EVENTS=message,message.ack.

  Available Webhook Events:

  Event	Description
  message	Text, media, contact, location messages
  message.reaction	Emoji reactions to messages
  message.revoked	Deleted/revoked messages
  message.edited	Edited messages
  message.ack	Delivery and read receipts
  message.deleted	Messages deleted for the user
  chat_presence	Typing and recording indicators from contacts
  group.participants	Group member join/leave/promote/demote events
  group.joined	You were added to a group
  label.edit	WhatsApp label metadata changed
  label.association	Label applied to or removed from a chat
  newsletter.joined	You subscribed to a newsletter/channel
  newsletter.left	You unsubscribed from a newsletter
  newsletter.message	New message(s) posted in a newsletter
  newsletter.mute	Newsletter mute setting changed
  call.offer	Incoming call received

  If this setting is empty, all events are forwarded.

• Webhook JID filtering

  You can skip events for specific chats or senders (for example, mute all groups) before they are forwarded:

  • --webhook-ignore-jids="@g.us,628123456789@s.whatsapp.net" (a comma-separated list), or

  • WHATSAPP_WEBHOOK_IGNORE_JIDS=@g.us.

  • Supports the @g.us / @s.whatsapp.net / @lid wildcards (match a whole address space) and exact JIDs.

  • This filters by conversation or sender and is independent of --webhook-events, which filters by event type. The Chatwoot integration has a separate CHATWOOT_IGNORE_JIDS setting.

• Webhook TLS configuration

  If you encounter TLS certificate verification errors when using webhooks (e.g., with Cloudflare tunnels or self-signed certificates):

  tls: failed to verify certificate: x509: certificate signed by unknown authority

  You can disable TLS certificate verification with:

  • --webhook-insecure-skip-verify=true, or

  • WHATSAPP_WEBHOOK_INSECURE_SKIP_VERIFY=true.

  Security Warning: This option disables TLS certificate verification and should only be used in:

  • Development or testing environments.

  • Cloudflare tunnels, which provide their own security layer.

  • Internal networks with self-signed certificates.

  For production environments, use a valid TLS certificate (for example, from Let's Encrypt) instead of disabling verification.

Configuration

Configuration is loaded in this order of priority:

1. Command-line flags (highest priority)

2. Environment variables

3. .env file (lowest priority)

Environment Variables

To use environment variables:

1. From the repository root, copy the example file: cp src/.env.example src/.env.

2. Update the values in src/.env as needed.

3. Alternatively, set the same variables in the process environment.

Available Environment Variables

Documentation:

• For detailed webhook payload schemas, security implementation, and integration examples, see Webhook Payload Documentation.

• For the comprehensive Chatwoot integration guide, see Chatwoot Integration Documentation.

• For OAuth deployment and security details, see MCP OAuth.

Run ./whatsapp --help to see all command-line flags.

Requirements

System Requirements

• Go 1.26.0 or later (when building from source)

• FFmpeg (for media processing)

Supported Platforms

• Linux (x86_64, ARM64)

• macOS (Intel, Apple Silicon)

• Windows (x86_64; WSL recommended)

Dependencies (without Docker)

• macOS:

  • brew install ffmpeg webp

  • export CGO_CFLAGS_ALLOW="-Xpreprocessor"

• Linux:

  • sudo apt update

  • sudo apt install ffmpeg webp

• Windows (WSL is recommended; see Install WSL):

  • Install FFmpeg.

  • Install libwebp, then extract it and add its bin directory to PATH.

Note: The webp package provides cwebp (encoder), dwebp (decoder), and webpmux (frame extractor) tools. FFmpeg is required for media processing. The libwebp tools (webpmux + dwebp) are used for animated WebP sticker support.

How to use

Basic

1. Clone the repository: git clone https://github.com/dresar/gowanew.

2. Open the cloned directory in a terminal.

3. Run cd src.

4. Run go run . rest.

5. Open http://localhost:3000.

Docker

Docker avoids the need to install Go, FFmpeg, and libwebp directly on the host.

1. Clone the repository: git clone https://github.com/dresar/gowanew.

2. Open the cloned directory in a terminal.

3. Copy the environment file: cp src/.env.example src/.env.

4. Run docker compose up -d --build.

5. Open http://localhost:3000.

Build your own binary

1. Clone the repository: git clone https://github.com/dresar/gowanew.

2. Open the cloned directory in a terminal.

3. Run cd src.

4. Build the binary:

   • Linux and macOS: go build -o whatsapp

   • Windows (Command Prompt or PowerShell): go build -o whatsapp.exe

5. Start the server:

   • Linux and macOS: ./whatsapp rest

   • Windows: .\whatsapp.exe rest

6. Open http://localhost:3000 in a browser.

Run ./whatsapp --help (or .\whatsapp.exe --help on Windows) to see all flags.

Cross-compile for Raspberry Pi (ARM)

To build for a Raspberry Pi or another ARM device without a C toolchain (CGO), use the purego build tag. This selects a pure-Go SQLite implementation.

1. Clone the repository: git clone https://github.com/dresar/gowanew.

2. Open the cloned directory in a terminal.

3. Run cd src.

4. Build for Raspberry Pi Zero / 1 (ARMv6):

   CGO_ENABLED=0 GOOS=linux GOARCH=arm GOARM=6 go build -tags purego -o whatsapp-armv6

5. Build for Raspberry Pi 2 / 3 / 4 (ARMv7 32-bit):

   CGO_ENABLED=0 GOOS=linux GOARCH=arm GOARM=7 go build -tags purego -o whatsapp-armv7

6. Transfer the binary to your Pi, give it execution permission (chmod +x), and run it:

   • If you built ARMv6: ./whatsapp-armv6 rest

   • If you built ARMv7: ./whatsapp-armv7 rest

MCP Server (Model Context Protocol)

MCP is not a separate mode or process — it's served by the REST server itself. Whenever ./whatsapp rest is running, the MCP endpoint is available at http://<host>:<port><base-path>/mcp (default http://localhost:3000/mcp) using the streamable HTTP transport. Disable it with MCP_ENABLED=false or --mcp-enabled=false (default: enabled).

Available MCP Tools

There are six consolidated tools; agents choose behavior through a type/action argument instead of one tool per operation:

whatsapp_send also accepts scheduled_at, timezone, recurrence, weekdays, day_of_month, end_at, and occurrence_limit to schedule the message instead of sending it now; manage the result with whatsapp_schedule.

Device selection

For multi-device deployments, the X-Device-Id header on the MCP client connection selects the device used by every tool call on that connection. If omitted, it falls back to the default device, just like REST. Any individual call can override it with an optional device_id argument.

MCP Configuration

Point your MCP client at the /mcp endpoint. It inherits the REST server's Basic Auth, so include the same Authorization header your REST calls use:

{
  "mcpServers": {
    "whatsapp": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Basic dXNlcjpzZWNyZXQ=",
        "X-Device-Id": "628123456789"
      }
    }
  }
}

headers is optional: include Authorization only when Basic Auth is configured, and X-Device-Id only for multi-device setups.

OAuth for remote MCP clients

OAuth 2.1 is available for remote clients that cannot attach a Basic Auth header. It is disabled by default. A minimal configuration is:

APP_BASIC_AUTH=admin:replace-with-a-strong-password
MCP_ENABLED=true
MCP_OAUTH_ENABLED=true
MCP_OAUTH_ISSUER_URL=https://gowa.example.com

When OAuth is enabled, /mcp accepts either a Bearer token or the configured Basic Auth credentials. OAuth does not authenticate REST or UI routes. See MCP OAuth for client setup, reverse-proxy requirements, subpath behavior, and the security model.

Migrating from the standalone MCP mode

• ./whatsapp mcp → ./whatsapp rest (MCP is now included automatically).

• http://localhost:8080/sse → http://localhost:3000/mcp.

• 40 granular tools → 5 consolidated tools (agents choose actions through the type/action field).

Production REST Server (Docker)

Using Docker Hub:

docker volume create whatsapp-storages
docker volume create whatsapp-statics
docker run --detach \
  --publish 3000:3000 \
  --name whatsapp \
  --restart always \
  --volume whatsapp-storages:/app/storages \
  --volume whatsapp-statics:/app/statics \
  dresar/gowanew \
  rest --autoreply="Don't reply to this message, please"

Using GitHub Container Registry:

docker volume create whatsapp-storages
docker volume create whatsapp-statics
docker run --detach \
  --publish 3000:3000 \
  --name whatsapp \
  --restart always \
  --volume whatsapp-storages:/app/storages \
  --volume whatsapp-statics:/app/statics \
  ghcr.io/dresar/gowanew \
  rest --autoreply="Don't reply to this message, please"

Production REST Server (Docker Compose)

Create a docker-compose.yml file with one of the following configurations.

Using Docker Hub:

services:
  whatsapp:
    image: dresar/gowanew
    container_name: whatsapp
    restart: always
    ports:
      - "3000:3000"
    volumes:
      - whatsapp_storages:/app/storages
      - whatsapp_statics:/app/statics
    command:
      - rest
      - --basic-auth=admin:admin
      - --port=3000
      - --debug=true
      - --os=Chrome
      - --account-validation=false

volumes:
  whatsapp_storages:
  whatsapp_statics:

Using GitHub Container Registry:

services:
  whatsapp:
    image: ghcr.io/dresar/gowanew
    container_name: whatsapp
    restart: always
    ports:
      - "3000:3000"
    volumes:
      - whatsapp_storages:/app/storages
      - whatsapp_statics:/app/statics
    command:
      - rest
      - --basic-auth=admin:admin
      - --port=3000
      - --debug=true
      - --os=Chrome
      - --account-validation=false

volumes:
  whatsapp_storages:
  whatsapp_statics:

Using environment variables with Docker Hub:

services:
  whatsapp:
    image: dresar/gowanew
    container_name: whatsapp
    restart: always
    ports:
      - "3000:3000"
    volumes:
      - whatsapp_storages:/app/storages
      - whatsapp_statics:/app/statics
    environment:
      - APP_BASIC_AUTH=admin:admin
      - APP_PORT=3000
      - APP_DEBUG=true
      - APP_OS=Chrome
      - WHATSAPP_ACCOUNT_VALIDATION=false

volumes:
  whatsapp_storages:
  whatsapp_statics:

Using environment variables with GitHub Container Registry:

services:
  whatsapp:
    image: ghcr.io/dresar/gowanew
    container_name: whatsapp
    restart: always
    ports:
      - "3000:3000"
    volumes:
      - whatsapp_storages:/app/storages
      - whatsapp_statics:/app/statics
    environment:
      - APP_BASIC_AUTH=admin:admin
      - APP_PORT=3000
      - APP_DEBUG=true
      - APP_OS=Chrome
      - WHATSAPP_ACCOUNT_VALIDATION=false

volumes:
  whatsapp_storages:
  whatsapp_statics:

Start the selected stack with docker compose up -d.

Production Server (Binary)

Download a binary from the releases page, then run it with the rest subcommand.

You may also fork or modify the source code.

Current API

MCP (Model Context Protocol) API

• Served at /mcp by the REST server using streamable HTTP whenever MCP_ENABLED is true. With APP_BASE_PATH set, the route is <base-path>/mcp.

• Available tools are listed in the "Available MCP Tools" section above.

• Compatible with MCP-enabled AI tools and agents.

HTTP REST API

• Check docs/openapi.yaml for detailed API specifications.

• Use Swagger Editor to visualize the API.

• Generate HTTP clients using openapi-generator.

✅ = available. * = has known limitations; see the notes below.

Notes:

• *List My Groups: Returns a maximum of 500 groups because of a WhatsApp protocol limitation. WhatsApp's servers, not this API, enforce the limit. See the whatsmeow source for details.

• /health is public and always registered at the root path, even when APP_BASE_PATH is set.

• Chatwoot routes are registered only when CHATWOOT_ENABLED=true.

User Interface

MCP UI

• Set up MCP (tested in Cursor)

• Test MCP

• Successful MCP setup

Web dashboard (gowa-ui)

The dashboard lives in its own repository: dresar/gowa-ui. Each gowa-ui release publishes a single self-contained gowa-ui.html; the server downloads the latest release at startup (and every APP_UI_UPDATE_INTERVAL, which defaults to 3h), verifies its SHA-256 digest, caches it under storages/ui/, and serves it at / behind Basic Auth.

Trust model: the release digest proves the download matches what GitHub advertises, not who published it. Operators who audit a specific build can pin it with APP_UI_ASSET_SHA256 (each release ships a .sha256 asset—this is the only setting that pins an exact build), point APP_UI_REPO at a fork they control (the updater still tracks that repo's latest release), or pre-seed the cache and disable auto-update entirely.

Air-gapped servers: place a downloaded gowa-ui.html at storages/ui/index.html and set APP_UI_AUTO_UPDATE=false. The dashboard can also be self-hosted anywhere static and pointed at this server's URL (see the gowa-ui README).

macOS Note

If you see invalid flag in pkg-config --cflags: -Xpreprocessor, run:

export CGO_CFLAGS_ALLOW="-Xpreprocessor"

Important

• This project is unofficial and not affiliated with WhatsApp.

• Use the official WhatsApp Business Platform when you require a supported, production-grade integration.