samihalawa-whatsapp-go-mcp

<div align="center">
  
  <img src="src/views/assets/gowa.svg" alt="GoWA Logo" width="200" height="200">

## Golang WhatsApp - Built with Go for efficient memory use

</div>

[![smithery badge](https://smithery.ai/badge/@samihalawa/whatsapp-go-mcp)](https://smithery.ai/server/@samihalawa/whatsapp-go-mcp)
[![Patreon](https://img.shields.io/badge/Support%20on-Patreon-orange.svg)](https://www.patreon.com/c/aldinokemal)
**If you're using this tools to generate income, consider supporting its development by becoming a Patreon member!**
Your support helps ensure the library stays maintained and receives regular updates!
___

![release version](https://img.shields.io/github/v/release/aldinokemal/go-whatsapp-web-multidevice)
![Build Image](https://github.com/aldinokemal/go-whatsapp-web-multidevice/actions/workflows/build-docker-image.yaml/badge.svg)
![Binary Release](https://github.com/aldinokemal/go-whatsapp-web-multidevice/actions/workflows/release.yml/badge.svg)

## Support for `ARM` & `AMD` Architecture along with `MCP` Support

Download:

- [Release](https://github.com/aldinokemal/go-whatsapp-web-multidevice/releases/latest)
- [Docker Hub](https://hub.docker.com/r/aldinokemal2104/go-whatsapp-web-multidevice/tags)
- [GitHub Container Registry](https://github.com/aldinokemal/go-whatsapp-web-multidevice/pkgs/container/go-whatsapp-web-multidevice)

## Support n8n package (n8n.io)

- [n8n package](https://www.npmjs.com/package/@aldinokemal2104/n8n-nodes-gowa)
- Go to Settings -> Community Nodes -> Input `@aldinokemal2104/n8n-nodes-gowa` -> Install

## Breaking Changes

- `v6`
  - For REST mode, you need to run `<binary> rest` instead of `<binary>`
    - for example: `./whatsapp rest` instead of ~~./whatsapp~~
  - For MCP mode, you need to run `<binary> mcp`
    - for example: `./whatsapp mcp`
- `v7`
  - Starting version 7.x we are using goreleaser to build the binary, so you can download the binary
      from [release](https://github.com/aldinokemal/go-whatsapp-web-multidevice/releases/latest)

## Feature

- Send WhatsApp message via http API, [docs/openapi.yml](./docs/openapi.yaml) for more details
- **MCP (Model Context Protocol) Server Support** - Integrate with AI agents and tools using standardized protocol
- Mention someone
  - `@phoneNumber`
  - example: `Hello @628974812XXXX, @628974812XXXX`
- Post Whatsapp Status
- Compress image before send
- Compress video before send
- Change OS name become your app (it's the device name when connect via mobile)
  - `--os=Chrome` or `--os=MyApplication`
- Basic Auth (able to add multi credentials)
  - `--basic-auth=kemal:secret,toni:password,userName:secretPassword`, or you can simplify
  - `-b=kemal:secret,toni:password,userName:secretPassword`
- Subpath deployment support
  - `--base-path="/gowa"` (allows deployment under a specific path like `/gowa/sub/path`)
- Customizable port and debug mode
  - `--port 8000`
  - `--debug true`
- Auto reply message
  - `--autoreply="Don't reply this message"`
- Auto mark read incoming messages
  - `--auto-mark-read=true` (automatically marks incoming messages as read)
- Webhook for received message
  - `--webhook="http://yourwebhook.site/handler"`, or you can simplify
  - `-w="http://yourwebhook.site/handler"`
  - for more detail, see [Webhook Payload Documentation](./docs/webhook-payload.md)
- Webhook Secret
  Our webhook will be sent to you with an HMAC header and a sha256 default key `secret`.

  You may modify this by using the option below:
  - `--webhook-secret="secret"`
- **Webhook Payload Documentation**
  For detailed webhook payload schemas, security implementation, and integration examples,
  see [Webhook Payload Documentation](./docs/webhook-payload.md)

## Configuration

You can configure the application using either command-line flags (shown above) or environment variables. Configuration
can be set in three ways (in order of priority):

1. Command-line flags (highest priority)
2. Environment variables
3. `.env` file (lowest priority)

### Environment Variables

You can configure the application using environment variables. Configuration can be set in three ways (in order of
priority):

1. Command-line flags (highest priority)
2. Environment variables
3. `.env` file (lowest priority)

To use environment variables:

1. Copy `.env.example` to `.env` in your project root (`cp src/.env.example src/.env`)
2. Modify the values in `.env` according to your needs
3. Or set the same variables as system environment variables

#### Available Environment Variables

| Variable                      | Description                                 | Default                                      | Example                                     |
|-------------------------------|---------------------------------------------|----------------------------------------------|---------------------------------------------|
| `APP_PORT`                    | Application port                            | `3000`                                       | `APP_PORT=8080`                             |
| `APP_DEBUG`                   | Enable debug logging                        | `false`                                      | `APP_DEBUG=true`                            |
| `APP_OS`                      | OS name (device name in WhatsApp)           | `Chrome`                                     | `APP_OS=MyApp`                              |
| `APP_BASIC_AUTH`              | Basic authentication credentials            | -                                            | `APP_BASIC_AUTH=user1:pass1,user2:pass2`    |
| `APP_BASE_PATH`               | Base path for subpath deployment            | -                                            | `APP_BASE_PATH=/gowa`                       |
| `DB_URI`                      | Database connection URI                     | `file:storages/whatsapp.db?_foreign_keys=on` | `DB_URI=postgres://user:pass@host/db`       |
| `WHATSAPP_AUTO_REPLY`         | Auto-reply message                          | -                                            | `WHATSAPP_AUTO_REPLY="Auto reply message"`  |
| `WHATSAPP_AUTO_MARK_READ`     | Auto-mark incoming messages as read         | `false`                                      | `WHATSAPP_AUTO_MARK_READ=true`              |
| `WHATSAPP_WEBHOOK`            | Webhook URL(s) for events (comma-separated) | -                                            | `WHATSAPP_WEBHOOK=https://webhook.site/xxx` |
| `WHATSAPP_WEBHOOK_SECRET`     | Webhook secret for validation               | `secret`                                     | `WHATSAPP_WEBHOOK_SECRET=super-secret-key`  |
| `WHATSAPP_ACCOUNT_VALIDATION` | Enable account validation                   | `true`                                       | `WHATSAPP_ACCOUNT_VALIDATION=false`         |
| `WHATSAPP_CHAT_STORAGE`       | Enable chat storage                         | `true`                                       | `WHATSAPP_CHAT_STORAGE=false`               |

Note: Command-line flags will override any values set in environment variables or `.env` file.

- For more command `./whatsapp --help`

## Requirements

### System Requirements

- **Go 1.24.0 or higher** (for building from source)
- **FFmpeg** (for media processing)

### Platform Support

- Linux (x86_64, ARM64)
- macOS (Intel, Apple Silicon)
- Windows (x86_64) - WSL recommended

### Dependencies (without docker)

- Mac OS:
  - `brew install ffmpeg`
  - `export CGO_CFLAGS_ALLOW="-Xpreprocessor"`
- Linux:
  - `sudo apt update`
  - `sudo apt install ffmpeg`
- Windows (not recomended, prefer using [WSL](https://docs.microsoft.com/en-us/windows/wsl/install)):
  - install ffmpeg, [download here](https://www.ffmpeg.org/download.html#build-windows)
  - add to ffmpeg to [environment variable](https://www.google.com/search?q=windows+add+to+environment+path)

## How to use

### Basic

1. Clone this repo: `git clone https://github.com/aldinokemal/go-whatsapp-web-multidevice`
2. Open the folder that was cloned via cmd/terminal.
3. run `cd src`
4. run `go run . rest` (for REST API mode)
5. Open `http://localhost:3000`

### Docker (you don't need to install in required)

1. Clone this repo: `git clone https://github.com/aldinokemal/go-whatsapp-web-multidevice`
2. Open the folder that was cloned via cmd/terminal.
3. run `docker-compose up -d --build`
4. open `http://localhost:3000`

### Build your own binary

1. Clone this repo `git clone https://github.com/aldinokemal/go-whatsapp-web-multidevice`
2. Open the folder that was cloned via cmd/terminal.
3. run `cd src`
4. run
    1. Linux & MacOS: `go build -o whatsapp`
    2. Windows (CMD / PowerShell): `go build -o whatsapp.exe`
5. run
    1. Linux & MacOS: `./whatsapp rest` (for REST API mode)
        1. run `./whatsapp --help` for more detail flags
    2. Windows: `.\whatsapp.exe rest` (for REST API mode)
        1. run `.\whatsapp.exe --help` for more detail flags
6. open `http://localhost:3000` in browser

### MCP Server (Model Context Protocol)

This application can also run as an MCP server, allowing AI agents and tools to interact with WhatsApp through a
standardized protocol.

1. Clone this repo `git clone https://github.com/aldinokemal/go-whatsapp-web-multidevice`
2. Open the folder that was cloned via cmd/terminal.
3. run `cd src`
4. run `go run . mcp` or build the binary and run `./whatsapp mcp`
5. The MCP server will start on `http://localhost:8080` by default

#### MCP Server Options

- `--host localhost` - Set the host for MCP server (default: localhost)
- `--port 8080` - Set the port for MCP server (default: 8080)

#### Available MCP Tools

- `whatsapp_send_text` - Send text messages
- `whatsapp_send_contact` - Send contact cards
- `whatsapp_send_link` - Send links with captions
- `whatsapp_send_location` - Send location coordinates

#### MCP Endpoints

- SSE endpoint: `http://localhost:8080/sse`
- Message endpoint: `http://localhost:8080/message`

### MCP Configuration

Make sure you have the MCP server running: `./whatsapp mcp`

For AI tools that support MCP with SSE (like Cursor), add this configuration:

```json
{
  "mcpServers": {
    "whatsapp": {
      "url": "http://localhost:8080/sse"
    }
  }
}

本番モード REST（docker）

Docker Hub を使用する場合：

docker run --detach --publish=3000:3000 --name=whatsapp --restart=always --volume=$(docker volume create --name=whatsapp):/app/storages aldinokemal2104/go-whatsapp-web-multidevice rest --autoreply="Dont't reply this message please"

GitHub Container Registry を使用する場合：

docker run --detach --publish=3000:3000 --name=whatsapp --restart=always --volume=$(docker volume create --name=whatsapp):/app/storages ghcr.io/aldinokemal/go-whatsapp-web-multidevice rest --autoreply="Dont't reply this message please"

本番モード REST（docker compose）

次の設定で docker-compose.yml ファイルを作成します。

Docker Hub を使用する場合：

services:
  whatsapp:
    image: aldinokemal2104/go-whatsapp-web-multidevice
    container_name: whatsapp
    restart: always
    ports:
      - "3000:3000"
    volumes:
      - whatsapp:/app/storages
    command:
      - rest
      - --basic-auth=admin:admin
      - --port=3000
      - --debug=true
      - --os=Chrome
      - --account-validation=false

volumes:
  whatsapp:

GitHub Container Registry を使用する場合：

services:
  whatsapp:
    image: ghcr.io/aldinokemal/go-whatsapp-web-multidevice
    container_name: whatsapp
    restart: always
    ports:
      - "3000:3000"
    volumes:
      - whatsapp:/app/storages
    command:
      - rest
      - --basic-auth=admin:admin
      - --port=3000
      - --debug=true
      - --os=Chrome
      - --account-validation=false

volumes:
  whatsapp:

または、env ファイルを使用する場合（Docker Hub）：

services:
  whatsapp:
    image: aldinokemal2104/go-whatsapp-web-multidevice
    container_name: whatsapp
    restart: always
    ports:
      - "3000:3000"
    volumes:
      - whatsapp:/app/storages
    environment:
      - APP_BASIC_AUTH=admin:admin
      - APP_PORT=3000
      - APP_DEBUG=true
      - APP_OS=Chrome
      - APP_ACCOUNT_VALIDATION=false

volumes:
  whatsapp:

または、env ファイルを使用する場合（GitHub Container Registry）：

services:
  whatsapp:
    image: ghcr.io/aldinokemal/go-whatsapp-web-multidevice
    container_name: whatsapp
    restart: always
    ports:
      - "3000:3000"
    volumes:
      - whatsapp:/app/storages
    environment:
      - APP_BASIC_AUTH=admin:admin
      - APP_PORT=3000
      - APP_DEBUG=true
      - APP_OS=Chrome
      - APP_ACCOUNT_VALIDATION=false

volumes:
  whatsapp:

本番モード（バイナリ）

• リリースからバイナリをダウンロードします。

このソースコードはフォークまたは編集できます。

現在の API

MCP（Model Context Protocol）API

• MCP サーバーは、AI エージェントが WhatsApp とやり取りするための標準化されたツールを提供します。
• Server-Sent Events（SSE）トランスポートをサポートしています。
• 利用可能なツール：whatsapp_send_text、whatsapp_send_contact、whatsapp_send_link、whatsapp_send_location
• MCP 対応の AI ツールおよびエージェントと互換性があります。

HTTP REST API

• API 仕様書。
• 詳細な API 仕様については、docs/openapi.ymlを確認してください。
• SwaggerEditorを使用して API を可視化できます。
• openapi-generatorを使用して HTTP クライアントを生成できます。 | 機能 | メニュー | メソッド | URL | |---------|----------------------------------------|--------|-------------------------------------| | ✅ | QR コードをスキャンしてログイン | GET | /app/login | | ✅ | ペアコードでログイン | GET | /app/login-with-code | | ✅ | ログアウト | GET | /app/logout |
  | ✅ | 再接続 | GET | /app/reconnect | | ✅ | デバイス | GET | /app/devices | | ✅ | ユーザー情報 | GET | /user/info | | ✅ | ユーザーのアバター | GET | /user/avatar | | ✅ | ユーザーのアバターを変更 | POST | /user/avatar | | ✅ | ユーザーの表示名を変更 | POST | /user/pushname | | ✅ | 自分のグループ | GET | /user/my/groups | | ✅ | 自分のニュースレター | GET | /user/my/newsletters | | ✅ | 自分のプライバシー設定 | GET | /user/my/privacy | | ✅ | 自分の連絡先 | GET | /user/my/contacts | | ✅ | ユーザーを確認 | GET | /user/check | | ✅ | ユーザーのビジネスプロフィール | GET | /user/business-profile | | ✅ | メッセージを送信 | POST | /send/message | | ✅ | 画像を送信 | POST | /send/image | | ✅ | 音声を送信 | POST | /send/audio | | ✅ | ファイルを送信 | POST | /send/file | | ✅ | 動画を送信 | POST | /send/video | | ✅ | 連絡先を送信 | POST | /send/contact | | ✅ | リンクを送信 | POST | /send/link | | ✅ | 位置情報を送信 | POST | /send/location | | ✅ | 投票を送信／投票する | POST | /send/poll | | ✅ | プレゼンスを送信 | POST | /send/presence | | ✅ | チャットのプレゼンスを送信（入力中インジケーター） | POST | /send/chat-presence | | ✅ | メッセージを取り消す | POST | /message/:message_id/revoke | | ✅ | メッセージにリアクションする | POST | /message/:message_id/reaction | | ✅ | メッセージを削除 | POST | /message/:message_id/delete | | ✅ | メッセージを編集 | POST | /message/:message_id/update | | ✅ | メッセージを既読にする（DM） | POST | /message/:message_id/read | | ✅ | メッセージにスターを付ける | POST | /message/:message_id/star | | ✅ | メッセージのスターを外す | POST | /message/:message_id/unstar | | ✅ | リンクでグループに参加 | POST | /group/join-with-link | | ✅ | リンクからグループ情報を取得 | GET | /group/info-from-link | | ✅ | グループ情報 | GET | /group/info | | ✅ | グループを退出 | POST | /group/leave | | ✅ | グループを作成 | POST | /group | | ✅ | グループに参加者を追加 | POST | /group/participants | | ✅ | グループから参加者を削除 | POST | /group/participants/remove | | ✅ | グループの参加者を昇格 | POST | /group/participants/promote | | ✅ | グループの参加者を降格 | POST | /group/participants/demote | | ✅ | グループの参加リクエスト一覧を取得 | GET | /group/participant-requests | | ✅ | グループの参加リクエストを承認 | POST | /group/participant-requests/approve | | ✅ | グループの参加リクエストを拒否 | POST | /group/participant-requests/reject | | ✅ | グループの写真を設定 | POST | /group/photo | | ✅ | グループ名を設定 | POST | /group/name | | ✅ | グループをロック状態に設定 | POST | /group/locked | | ✅ | グループをアナウンスモードに設定 | POST | /group/announce | | ✅ | グループのトピックを設定 | POST | /group/topic | | ✅ | グループの招待リンクを取得 | GET | /group/invite-link | | ✅ | ニュースレターのフォローを解除 | POST | /newsletter/unfollow | | ✅ | チャット一覧を取得 | GET | /chats | | ✅ | チャットメッセージを取得 | GET | /chat/:chat_jid/messages | | ✅ | チャットにラベルを付ける | POST | /chat/:chat_jid/label | | ✅ | チャットをピン留め | POST | /chat/:chat_jid/pin |

✅ = Available
❌ = Not Available Yet

ユーザーインターフェース

MCP UI

• MCP のセットアップ（cursor でテスト済み）
• MCP のテスト
• MCP のセットアップ完了

HTTP REST API UI

説明	画像
ホームページ
ログイン
コードでログイン
メッセージを送信
画像を送信
ファイルを送信
動画を送信
連絡先を送信
位置情報を送信
音声を送信
投票を送信
プレゼンスを送信
リンクを送信
自分のグループ
リンクからグループ情報
グループを作成
リンクでグループに参加
参加者を管理
自分のニュースレター
自分の連絡先
ビジネスプロフィール

Mac OS の注意事項

• エラー（pkg-config --cflags の無効なフラグ：-Xpreprocessor）が発生した場合は、次のコマンドを実行してください。 export CGO_CFLAGS_ALLOW="-Xpreprocessor"

重要

• このプロジェクトは非公式であり、WhatsApp とは提携していません。
• 問題を避けるため、公式の WhatsApp API を使用してください。
• whatsmeow ライブラリの制限により、MCP または REST API のいずれか一方しか実行できません。独立した MCP は今後利用可能になる予定です。