WhatsApp Web MCP

A Node.js application that connects WhatsApp Web with AI models through the Model Context Protocol (MCP). This project provides a standardized interface for programmatic interaction with WhatsApp, enabling automated messaging, contact management, and group chat functionality through AI-driven workflows.

Overview

WhatsApp Web MCP provides a seamless integration between WhatsApp Web and AI models by:

- Creating a standardized interface through the Model Context Protocol (MCP)
- Offering MCP Server access to WhatsApp functionality
- Providing flexible deployment options through SSE or Command modes
- Supporting both direct WhatsApp client integration and API-based connectivity

Disclaimer

IMPORTANT: This tool is for testing purposes only and should not be used in production environments.

Disclaimer from WhatsApp Web project:

> This project is not affiliated, associated, authorized, endorsed by, or in any way officially connected with WhatsApp or any of its subsidiaries or its affiliates. The official WhatsApp website can be found at whatsapp.com. "WhatsApp" as well as related names, marks, emblems and images are registered trademarks of their respective owners. Also it is not guaranteed you will not be blocked by using this method. WhatsApp does not allow bots or unofficial clients on their platform, so this shouldn't be considered totally safe.

Learning Resources

To learn more about using WhatsApp Web MCP in real-world scenarios, check out these articles:

- Integrating WhatsApp with AI: Guide to Setting Up a WhatsApp MCP server
- Integrating OpenAI Agents Python SDK with Anthropic's MCP

Installation

1. Clone the repository:

   git clone https://github.com/pnizer/wweb-mcp.git
   cd wweb-mcp
   

2. Install globally or use with npx:

   # Install globally
   npm install -g .
# Or use with npx directly

   npx .

   

3. Build with Docker:

   docker build . -t wweb-mcp:latest

   

Configuration

Command Line Options

| Option | Alias | Description | Choices | Default |
|--------|-------|-------------|---------|---------|
| --mode | -m | Run mode | mcp, whatsapp-api | mcp |
| --mcp-mode | -c | MCP connection mode | standalone, api | standalone |
| --transport | -t | MCP transport mode | sse, command | sse |
| --sse-port | -p | Port for SSE server | - | 3002 |
| --api-port | - | Port for WhatsApp API server | - | 3001 |
| --auth-data-path | -a | Path to store authentication data | - | .wwebjs_auth |
| --auth-strategy | -s | Authentication strategy | local, none | local |
| --api-base-url | -b | API base URL for MCP when using api mode | - | http://localhost:3001/api |
| --api-key | -k | API key for WhatsApp Web REST API when using api mode | - | '' |

API Key Authentication

When running in API mode, the WhatsApp API server requires authentication using an API key. The API key is automatically generated when you start the WhatsApp API server and is displayed in the logs:

WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

To connect the MCP server to the WhatsApp API server, you need to provide this API key using the --api-key or -k option:

npx wweb-mcp --mode mcp --mcp-mode api --api-base-url http://localhost:3001/api --api-key 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

The API key is stored in the authentication data directory (specified by --auth-data-path) and persists between restarts of the WhatsApp API server.

Authentication Methods

Local Authentication (Recommended)

- Scan QR code once
- Credentials persist between sessions
- More stable for long-term operation

No Authentication

- Default method
- Requires QR code scan on each startup
- Suitable for testing and development

Webhook Configuration

You can configure webhooks to receive incoming WhatsApp messages by creating a webhook.json file in your authentication data directory (specified by --auth-data-path).

Webhook JSON Format

{
  "url": "https://your-webhook-endpoint.com/incoming",
  "authToken": "your-optional-authentication-token",
  "filters": {
    "allowedNumbers": ["+1234567890", "+0987654321"],
    "allowPrivate": true,
    "allowGroups": false
  }
}

Configuration Options

| Option | Type | Description |
|--------|------|-------------|
| url | String | The webhook endpoint URL where message data will be sent |
| authToken | String (optional) | Authentication token to be included in the Authorization header as a Bearer token |
| filters.allowedNumbers | Array (optional) | List of phone numbers to accept messages from. If provided, only messages from these numbers will trigger the webhook |
| filters.allowPrivate | Boolean (optional) | Whether to send private messages to the webhook. Default: true |
| filters.allowGroups | Boolean (optional) | Whether to send group messages to the webhook. Default: true |

Webhook Payload

When a message is received and passes the filters, a POST request will be sent to the configured URL with the following JSON payload:

{
  "from": "+1234567890",
  "name": "Contact Name",
  "message": "Hello, world!",
  "isGroup": false,
  "timestamp": 1621234567890,
  "messageId": "ABCDEF1234567890"
}

Usage

Running Modes

WhatsApp API Server

Run a standalone WhatsApp API server that exposes WhatsApp functionality through REST endpoints:

npx wweb-mcp --mode whatsapp-api --api-port 3001

MCP Server (Standalone)

Run an MCP server that directly connects to WhatsApp Web:

npx wweb-mcp --mode mcp --mcp-mode standalone --transport sse --sse-port 3002

MCP Server (API Client)

Run an MCP server that connects to the WhatsApp API server:

```bash