📌Overview

Purpose: To facilitate programmatic interaction with WhatsApp Web through AI models using the Model Context Protocol (MCP) for automated messaging and contact management.

Overview: WhatsApp Web MCP serves as a bridge between WhatsApp Web and AI models, providing a standardized interface for users to automate various functionalities like messaging, managing contacts, and coordinating group chats. By employing flexible deployment options, the framework allows for both direct integration with the WhatsApp client and connectivity through an API, catering to developers and businesses looking to leverage WhatsApp's capabilities in their applications.

Key Features:

Model Context Protocol (MCP): Provides a standardized interface that allows for seamless interactions between WhatsApp Web and AI models, facilitating automated workflows.
Flexible Deployment Options: Supports multiple modes of operation, including standalone MCP servers and WhatsApp API connections, enabling users to choose the best configuration for their needs.

WhatsApp Web MCP

A Node.js application that connects WhatsApp Web with AI models through the Model Context Protocol (MCP). It 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 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 with WhatsApp or its subsidiaries. Use is not guaranteed to avoid blocking. WhatsApp does not allow bots or unofficial clients, so this is not totally safe.

Learning Resources

To learn more about WhatsApp Web MCP, see these articles:

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

Installation

Clone the repository:

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

Install globally or use with npx:

# Install globally
npm install -g .

# Or use with npx directly
npx .

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 (api mode)	-	`http://localhost:3001/api`
`--api-key`	`-k`	API key for WhatsApp REST API (api mode)	-	`''`

API Key Authentication

In API mode, the WhatsApp API server requires an API key, displayed in logs when starting the server:

WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

Connect the MCP server using:

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

The API key persists between server restarts.

Authentication Methods

Local Authentication (Recommended): Scan QR code once; credentials persist; stable for long-term use.
No Authentication: Default; requires QR scan every startup; good for testing.

Webhook Configuration

Configure webhooks by creating a webhook.json in the authentication data directory.

Webhook JSON Format

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

Webhook Options

Option	Type	Description
`url`	String	Endpoint URL to receive message data
`authToken`	String	Optional token for Authorization header
`filters.allowedNumbers`	Array	Phone numbers to accept messages from
`filters.allowPrivate`	Boolean	Send private messages (default: `true`)
`filters.allowGroups`	Boolean	Send group messages (default: `true`)

Webhook Payload

Received messages trigger a POST with:

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

Usage

Running Modes

WhatsApp API Server

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

MCP Server (Standalone)

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

MCP Server (API Client)

Start API server first:

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

Start MCP server with API key:

npx wweb-mcp --mode mcp --mcp-mode api --api-base-url http://localhost:3001/api --api-key YOUR_API_KEY --transport sse --sse-port 3002

Available Tools

Tool	Description	Parameters
`get_status`	Check WhatsApp client connection	None
`send_message`	Send messages	`number`: Phone number `message`: Text content
`search_contacts`	Search contacts by name or number	`query`: Search term
`get_messages`	Retrieve messages from a chat	`number`: Phone number `limit` (optional)
`get_chats`	List all WhatsApp chats	None
`create_group`	Create a WhatsApp group	`name`: Group name `participants`: Array of numbers
`add_participants_to_group`	Add participants to a group	`groupId`: Group ID `participants`: Array of numbers
`get_group_messages`	Get messages from a group	`groupId`: Group ID `limit` (optional)
`send_group_message`	Send message to a group	`groupId`: Group ID `message`: Text content
`search_groups`	Search groups	`query`: Search term
`get_group_by_id`	Get group info	`groupId`: Group ID
`download_media_from_message`	Download media	`messageId`: Message ID
`send_media_message`	Send media to contact	`number`: Phone number `source`: Media URI (`http://`, `https://`, `file://`) `caption` (optional)

Available Resources

Resource URI	Description
`whatsapp://contacts`	All contacts
`whatsapp://messages/{number}`	Messages from chat
`whatsapp://chats`	All chats
`whatsapp://groups`	All groups
`whatsapp://groups/search`	Search groups
`whatsapp://groups/{groupId}/messages`	Messages from group

REST API Endpoints

Contacts & Messages

Endpoint	Method	Description	Parameters
`/api/status`	GET	WhatsApp connection status	None
`/api/contacts`	GET	All contacts	None
`/api/contacts/search`	GET	Search contacts	`query`: Search term
`/api/chats`	GET	All chats	None
`/api/messages/{number}`	GET	Messages from chat	`limit` (query): Number of messages
`/api/send`	POST	Send message	`number`: Recipient `message`: Content
`/api/send/media`	POST	Send media message	`number`: Recipient `source`: Media URI `caption` (optional)
`/api/messages/{messageId}/media/download`	POST	Download media	None

Group Management

Endpoint	Method	Description	Parameters
`/api/groups`	GET	All groups	None
`/api/groups/search`	GET	Search groups	`query`: Search term
`/api/groups/create`	POST	Create group	`name`: Group name `participants`: Array
`/api/groups/{groupId}`	GET	Group information	None
`/api/groups/{groupId}/messages`	GET	Group messages	`limit` (query): Number of messages
`/api/groups/{groupId}/participants/add`	POST	Add members	`participants`: Array
`/api/groups/send`	POST	Send message to group	`groupId`: Group ID `message`: Content

AI Integration

Claude Desktop Integration

Option 1: Using NPX

Start WhatsApp API server:
```
npx wweb-mcp -m whatsapp-api -s local
```
Scan the QR code with your WhatsApp app.
Note the API key from logs.

Add this to Claude Desktop configuration:

{
    "mcpServers": {
        "whatsapp": {
            "command": "npx",
            "args": [
                "wweb-mcp",
                "-m", "mcp",
                "-s", "local",
                "-c", "api",
                "-t", "command",
                "--api-base-url", "http://localhost:3001/api",
                "--api-key", "YOUR_API_KEY"
            ]
        }
    }
}

Option 2: Using Docker

Start WhatsApp API server in Docker:

docker run -i -p 3001:3001 -v wweb-mcp:/wwebjs_auth --rm wweb-mcp:latest -m whatsapp-api -s local -a /wwebjs_auth

Scan the QR code.
Note API key.

Add this to Claude Desktop configuration:

{
    "mcpServers": {
        "whatsapp": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "wweb-mcp:latest",
                "-m", "mcp",
                "-s", "local",
                "-c", "api",
                "-t", "command",
                "--api-base-url", "http://host.docker.internal:3001/api",
                "--api-key", "YOUR_API_KEY"
            ]
        }
    }
}

Restart Claude Desktop for changes to take effect.

Architecture

Components

WhatsAppService: Core logic for WhatsApp interaction
WhatsAppApiClient: Connects to WhatsApp API
API Router: Express REST API routes
MCP Server: Model Context Protocol implementation

Deployment Options

WhatsApp API Server
MCP Server (Standalone)
MCP Server (API Client)

This supports running servers on the same or different machines as needed.

Development

Project Structure

src/
├── whatsapp-client.ts
├── whatsapp-service.ts
├── whatsapp-api-client.ts
├── api.ts
├── mcp-server.ts
└── main.ts

Building

npm run build

Testing

npm test           # Run all tests
npm run test:watch # Watch mode
npm run test:coverage # Generate coverage report

Linting & Formatting

npm run lint       # Lint
npm run lint:fix   # Auto fix lint issues
npm run format     # Format with Prettier
npm run validate   # Lint + test

Publishing

Publishing uses GitHub Actions, automating version bumps, git tagging, and npm publishing. Requires NPM_TOKEN secret configured.

Troubleshooting

Cannot run wweb-mcp command standalone mode with Claude Desktop due to multiple Puppeteer sessions conflicting. Use MCP + API mode instead.

Features

Send/receive messages
Send media messages (images)
Download media (images, audio, documents)
Group chat management
Contact search
Message history retrieval

Upcoming Features

Support all media types (video, audio, docs)
Enhanced message templates
Advanced group management
Contact add/remove
Improved error handling

Contributing

Fork the repo
Create a feature branch
Commit changes
Push branch
Create Pull Request

Ensure PRs:

Follow code style
Include tests
Update docs
Detail changes

Dependencies

This project uses whatsapp-web.js, an unofficial JavaScript client for WhatsApp Web.

License

MIT License - see LICENSE file.

Logging

Built with Winston, the logging system offers:

Multiple levels: error, warn, info, http, debug
Colorized console output
HTTP request/response logging
Structured error handling
Environment-aware levels (dev vs prod)
Logs sent to stderr in MCP command mode

Log Levels

error - Critical errors
warn - Warnings that need attention
info - General application info
http - HTTP request logs
debug - Detailed debug info

Configuring Log Level

Use --log-level or -l flag:

npm start -- --log-level=debug

Or if installed globally:

wweb-mcp --log-level=debug

Command Mode Logging

In MCP command mode (--mode mcp --transport command), logs are directed to stderr to prevent interfering with MCP protocol communication on stdout.

Test Environment

When running tests or in test environment (NODE_ENV=test), the logger adjusts automatically for testing suitability.