home / mcp / whatsapp mcp server

WhatsApp MCP Server

Provides a multi-user MCP server with Supabase cloud storage, full history sync, and full-text search for WhatsApp data.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "ai-caseylai-whatsapp-mcp": {
      "command": "node",
      "args": [
        "/path/to/whatsapp-mcp/dist/index.js"
      ],
      "env": {
        "SUPABASE_URL": "your-supabase-url",
        "SUPABASE_SERVICE_KEY": "your-service-role-key",
        "WHATSAPP_AUTH_USER_ID": "user-123",
        "WHATSAPP_PHONE_NUMBER": "your-phone-number"
      }
    }
  }
}

This is a complete WhatsApp MCP Server that enables multiple users, cloud storage via Supabase, and full historical message synchronization using the Model Context Protocol (MCP). It provides independent WhatsApp connections per user, scalable storage, fast search, and secure data isolation to power multi-user messaging workflows.

How to use

You connect an MCP client to this server to manage WhatsApp conversations for multiple users. Each user gets an isolated WhatsApp session with access to messages, contacts, and media stored in the cloud. The server automatically syncs historical messages and supports full-text search and media handling across instances.

How to install

Prerequisites: Node.js and npm installed on your system.

1. Clone the project locally.

2. Install dependencies.

3. Set up Supabase and initialize the database.

4. Configure environment variables.

5. Build and run the server.

Configuration and usage notes

Key features include multi-user support, cloud persistence, historical message synchronization, full-text search, media handling, and secure data isolation driven by Row Level Security in Supabase.

Troubleshooting

If the QR code does not appear on startup, ensure your terminal supports displaying a QR code. If the connection drops, the client will attempt to reconnect automatically. If you need to re-login, remove the auth data directory and restart.

Security considerations

Data is isolated per user using Supabase Row Level Security. Authentication information is stored locally in an auth_info directory. OAuth integration is supported.

Tools and capabilities

The server exposes a set of tools to interact with WhatsApp data and the MCP server. See the list under Tools for all available actions.

OpenClaw integration example

To integrate with OpenClaw, configure the MCP server in your OpenClaw setup as shown below.

{
  "mcpServers": {
    "whatsapp": {
      "command": "node",
      "args": ["/path/to/whatsapp-mcp/dist/index.js"],
      "env": {
        "SUPABASE_URL": "your-supabase-url",
        "SUPABASE_SERVICE_KEY": "your-service-role-key",
        "WHATSAPP_PHONE_NUMBER": "your-phone-number"
      }
    }
  }
}

Notes

The server stores data in Supabase and supports incremental history synchronization for efficient data access.

License

MIT

Acknowledgments

Baileys - WhatsApp Web API, Model Context Protocol - MCP, Supabase - open source cloud alternative.

Available tools

whatsapp_search_contacts

Search contacts in the connected WhatsApp session.

whatsapp_list_chats

List all chats for a user.

whatsapp_get_chat

Retrieve details for a specific chat.

whatsapp_list_messages

List messages in a chat.

whatsapp_search_messages

Search messages by content.

whatsapp_send_message

Send a message to a chat or contact.

whatsapp_get_contact

Fetch contact details.

whatsapp_get_connection_status

Check the WhatsApp connection status.

whatsapp_sync_history

Trigger historical message synchronization.