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:

生产模式（二进制文件）

• 从 发布页面 下载二进制文件

你可以 Fork 或编辑此源代码！

当前 API

MCP（Model Context Protocol）API

• MCP 服务提供标准化工具，供 AI Agent 与 WhatsApp 交互
• 支持 Server-Sent Events（SSE）传输
• 可用工具：whatsapp_send_text、whatsapp_send_contact、whatsapp_send_link、whatsapp_send_location
• 兼容支持 MCP 的 AI 工具和 Agent

HTTP REST API

• API 规范文档。
• 查看 docs/openapi.yml 了解详细的 API 规范。
• 使用 SwaggerEditor 可视化 API。
• 使用 openapi-generator 生成 HTTP 客户端。 | 功能 | 菜单 | 方法 | URL | |---------|----------------------------------------|--------|-------------------------------------| | ✅ | 扫码登录 | 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 | | ✅ | 修改用户 PushName | POST | /user/pushname | | ✅ | 我的群组 | GET | /user/my/groups | | ✅ | 我的 Newsletter | 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 | | ✅ | 已读消息（私信） | 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 | | ✅ | 取消关注 Newsletter | 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 界面

• 设置 MCP（已在 cursor 中测试）
• 测试 MCP
• MCP 设置成功

HTTP REST API 界面

描述	图片
首页
登录
使用代码登录
发送消息
发送图片
发送文件
发送视频
发送联系人
发送位置
发送音频
发送投票
发送在线状态
发送链接
我的群组
从链接获取群组信息
创建群组
使用链接加入群组
管理参与者
我的频道
我的联系人
商家资料

Mac OS 注意事项

• 如果遇到错误（pkg-config --cflags 中有无效标志：-Xpreprocessor），请执行以下操作 export CGO_CFLAGS_ALLOW="-Xpreprocessor"

重要事项

• 本项目为非官方项目，与 WhatsApp 无关联。
• 为避免出现问题，请使用 WhatsApp 官方 API。
• 由于 whatsmeow 库的限制，我们只能运行 MCP 或 REST API。未来将提供独立的 MCP。