MCP Server - GOWA - Go WhatsApp Web Multi-Device API

Overview

The MCP (Model Context Protocol) server mode allows AI agents and tools to interact with WhatsApp through a standardized protocol using Server-Sent Events (SSE) transport.

MCP and REST modes cannot run simultaneously due to WhatsApp protocol limitations. Choose one mode based on your use case.

Getting Started

Starting the MCP Server

./whatsapp mcp

Server Configuration

# Set custom host and port
./whatsapp mcp --host localhost --port 8080

Flag	Default	Description
`--host`	`localhost`	Host address for the MCP server
`--port`	`8080`	Port for the MCP server

Endpoints

Once started, the MCP server exposes two endpoints:

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

MCP Configuration

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

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

Cursor IDE Setup

Open Cursor settings
Navigate to the MCP configuration section
Add the WhatsApp MCP server configuration:

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

Save and restart Cursor
The WhatsApp tools will now be available in your AI chat

Available Tools

The WhatsApp MCP server provides comprehensive tools for AI agents to interact with WhatsApp.

Connection Management

whatsapp_connection_status

Check whether the WhatsApp client is connected and logged in

whatsapp_login_qr

Initiate QR code based login flow with image output

whatsapp_login_with_code

Generate pairing code for multi-device login using phone number

whatsapp_logout

Sign out the current WhatsApp session

whatsapp_reconnect

Attempt to reconnect to WhatsApp using stored session

Messaging & Communication

whatsapp_send_text

Send text messages with reply and forwarding support, including ghost mentions

whatsapp_send_contact

Send contact cards with name and phone number

whatsapp_send_link

Send links with custom captions

whatsapp_send_location

Send location coordinates (latitude/longitude)

whatsapp_send_image

Send images with captions, compression, and view-once options

whatsapp_send_sticker

Send stickers with automatic WebP conversion (supports JPG/PNG/GIF)

Chat & Contact Management

whatsapp_list_contacts

Retrieve all contacts in your WhatsApp account

whatsapp_list_chats

Get recent chats with pagination and search filters

whatsapp_get_chat_messages

Fetch messages from specific chats with time/media filtering

whatsapp_download_message_media

Download images/videos from messages

whatsapp_archive_chat

Archive or unarchive a chat conversation

Group Management

whatsapp_group_create

Create new groups with optional initial participants

whatsapp_group_join_via_link

Join groups using invite links

whatsapp_group_leave

Leave groups by group ID

whatsapp_group_participants

List all participants in a group

whatsapp_group_manage_participants

Add, remove, promote, or demote group members

whatsapp_group_invite_link

Get or reset group invite links

whatsapp_group_info

Get detailed group information

whatsapp_group_set_name

Update group display name

whatsapp_group_set_topic

Update group description/topic

whatsapp_group_set_locked

Toggle admin-only group info editing

whatsapp_group_set_announce

Toggle announcement-only mode

whatsapp_group_join_requests

List pending join requests

whatsapp_group_manage_join_requests

Approve or reject join requests

Tool Examples

Sending a Text Message

{
  "tool": "whatsapp_send_text",
  "arguments": {
    "phone": "628123456789",
    "message": "Hello from MCP!",
    "is_forwarded": false
  }
}

Sending with Ghost Mentions

Ghost mentions allow you to mention users without showing @phone in the message text:

{
  "tool": "whatsapp_send_text",
  "arguments": {
    "phone": "[email protected]",
    "message": "Important announcement for everyone!",
    "mentions": ["@everyone"]
  }
}

Sending an Image

{
  "tool": "whatsapp_send_image",
  "arguments": {
    "phone": "628123456789",
    "image_url": "https://example.com/image.jpg",
    "caption": "Check this out!",
    "compress": true,
    "view_once": false
  }
}

Listing Chats

{
  "tool": "whatsapp_list_chats",
  "arguments": {
    "limit": 25,
    "offset": 0,
    "search": "customer",
    "has_media": false
  }
}

Creating a Group

{
  "tool": "whatsapp_group_create",
  "arguments": {
    "title": "Project Team",
    "participants": [
      "628123456789",
      "628987654321"
    ]
  }
}

Managing Group Participants

{
  "tool": "whatsapp_group_manage_participants",
  "arguments": {
    "group_id": "[email protected]",
    "participants": ["628123456789"],
    "action": "promote"
  }
}

Valid actions: add, remove, promote, demote

Device Management

The MCP server automatically uses the first available device. For multi-device scenarios, the server will select the default device.

Device selection in MCP mode follows the same rules as REST mode. If multiple devices are registered, ensure proper configuration.

Transport Details

Server-Sent Events (SSE)

The MCP server uses SSE transport for real-time communication with AI agents:

Keep-alive: Enabled by default
Base URL: http://localhost:8080
SSE Endpoint: /sse
Message Endpoint: /message

Message Format

All tool responses follow the MCP protocol format with structured data and fallback text:

{
  "structured": {
    "message_id": "3EB0C127D7BACC83D6A1",
    "status": "sent"
  },
  "fallback": "Message sent successfully with ID 3EB0C127D7BACC83D6A1"
}

Limitations

MCP and REST modes cannot run simultaneously
Only one MCP connection can be active at a time
Image-based tools (like QR login) return base64-encoded images

Use Cases

AI Assistants

Enable AI agents to send and receive WhatsApp messages on your behalf

Chatbots

Build intelligent chatbots that interact with WhatsApp contacts

Automation

Automate WhatsApp workflows through AI-driven interactions

Customer Support

Integrate AI-powered customer support via WhatsApp

Troubleshooting

MCP Server Not Starting

Check if port 8080 is already in use
Verify no other instance is running
Check for WhatsApp connection issues

Tools Not Responding

Verify the SSE connection is established
Check server logs for errors: --debug=true
Ensure device is connected and logged in

Debug Mode

Enable debug logging to troubleshoot issues:

./whatsapp mcp --debug=true

Or via environment variable:

APP_DEBUG=true ./whatsapp mcp

Example Integration

Here’s a complete example of setting up WhatsApp MCP with Cursor:

Start MCP Server

./whatsapp mcp --host localhost --port 8080

Configure Cursor

Add to your Cursor MCP settings:

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

Ask the AI: “Check WhatsApp connection status and login if needed”

Send Messages

Ask the AI: “Send a message to +628123456789 saying ‘Hello from MCP!’”

Get Started

Core Concepts

Guides

Integrations

Deployment

​Overview

​Getting Started

​Starting the MCP Server

​Server Configuration

​Endpoints

​MCP Configuration

​Cursor IDE Setup

​Available Tools

​Connection Management

whatsapp_connection_status

whatsapp_login_qr

whatsapp_login_with_code

whatsapp_logout

whatsapp_reconnect

​Messaging & Communication

whatsapp_send_text

whatsapp_send_contact

whatsapp_send_link

whatsapp_send_location

whatsapp_send_image

whatsapp_send_sticker

​Chat & Contact Management

whatsapp_list_contacts

whatsapp_list_chats

whatsapp_get_chat_messages

whatsapp_download_message_media

whatsapp_archive_chat

​Group Management

whatsapp_group_create

whatsapp_group_join_via_link

whatsapp_group_leave

whatsapp_group_participants

whatsapp_group_manage_participants

whatsapp_group_invite_link

whatsapp_group_info

whatsapp_group_set_name

whatsapp_group_set_topic

whatsapp_group_set_locked

whatsapp_group_set_announce

whatsapp_group_join_requests

whatsapp_group_manage_join_requests

​Tool Examples

​Sending a Text Message

​Sending with Ghost Mentions

​Sending an Image

​Listing Chats

​Creating a Group

​Managing Group Participants

​Device Management

​Transport Details

​Server-Sent Events (SSE)

​Message Format

​Limitations

​Use Cases

AI Assistants

Chatbots

Automation

Customer Support

​Troubleshooting

​MCP Server Not Starting

​Tools Not Responding

​Debug Mode

​Example Integration

Build docs developers (and LLMs) love

Overview

Getting Started

Starting the MCP Server

Server Configuration

Endpoints

MCP Configuration

Cursor IDE Setup

Available Tools

Connection Management

Messaging & Communication

Chat & Contact Management

Group Management

Tool Examples

Sending a Text Message

Sending with Ghost Mentions

Sending an Image

Listing Chats

Creating a Group

Managing Group Participants

Device Management

Transport Details

Server-Sent Events (SSE)

Message Format

Limitations

Use Cases

Troubleshooting

MCP Server Not Starting

Tools Not Responding

Debug Mode

Example Integration