WhatsApp Web - MCP Server

WhatsApp Web MCP

![PR Checks](https://github.com/pnizer/wweb-mcp/actions/workflows/pr-checks.yml/badge.svg)

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

Clone the repository:

Install globally or use with npx:

Build with Docker:

Configuration

Command Line Options

[object Object]	[object Object]	[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]	[object Object]	[object Object]

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:

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

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

Configuration Options

[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]

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:

Usage

Running Modes

WhatsApp API Server

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

MCP Server (Standalone)

Run an MCP server that directly connects to WhatsApp Web:

MCP Server (API Client)

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

Available Tools

[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]

Available Resources

[object Object]	[object Object]
[object Object]	[object Object]
[object Object]	[object Object]
[object Object]	[object Object]
[object Object]	[object Object]
[object Object]	[object Object]
[object Object]	[object Object]

REST API Endpoints

Contacts & Messages

[object Object]	[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]	[object Object]

Group Management

[object Object]	[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]	[object Object]

AI Integration

Claude Desktop Integration

Option 1: Using NPX

Start WhatsApp API server:

Scan the QR code with your WhatsApp mobile app

Note the API key displayed in the logs:

Add the following to your Claude Desktop configuration:

Option 2: Using Docker

Start WhatsApp API server in Docker:

Scan the QR code with your WhatsApp mobile app

Note the API key displayed in the logs:

Add the following to your Claude Desktop configuration:

Restart Claude Desktop

The WhatsApp functionality will be available through Claude's interface

Architecture

The project is structured with a clean separation of concerns:

Components

WhatsAppService: Core business logic for interacting with WhatsApp

WhatsAppApiClient: Client for connecting to the WhatsApp API

API Router: Express routes for the REST API

MCP Server: Model Context Protocol implementation

Deployment Options

WhatsApp API Server: Standalone REST API server

MCP Server (Standalone): Direct connection to WhatsApp Web

MCP Server (API Client): Connection to WhatsApp API server

This architecture allows for flexible deployment scenarios, including:

Running the API server and MCP server on different machines

Using the MCP server as a client to an existing API server

Running everything on a single machine for simplicity

Development

Project Structure

Building from Source

Testing

The project uses Jest for unit testing. To run the tests:

Linting and Formatting

The project uses ESLint and Prettier for code quality and formatting:

The linting configuration enforces TypeScript best practices and maintains consistent code style across the project.

Publishing

The project uses GitHub Actions for automated publishing to npm. The workflow handles:

Version incrementing (patch, minor, or major)

Git tagging with version prefixed by 'v' (e.g., v0.2.1)

Publishing to npm with GitHub secrets

To release a new version:

Go to the GitHub repository Actions tab

Select the "Publish Package" workflow

Click "Run workflow"

Choose the version increment type (patch, minor, or major)

Click "Run workflow" to start the publishing process

This workflow requires an NPM_TOKEN secret to be configured in your GitHub repository.

Troubleshooting

Claude Desktop Integration Issues

It's not possible to start wweb-mcp in command standalone mode on Claude because Claude opens more than one process, multiple times, and each wweb-mcp needs to open a puppeteer session that cannot share the same WhatsApp authentication. Because of this limitation, we've split the app into MCP and API modes to allow for proper integration with Claude.

Features

Sending and receiving messages

Sending media messages (images only)

Downloading media from messages (images, audio, documents)

Group chat management

Contact management and search

Message history retrieval

Upcoming Features

Support for sending all media file types (video, audio, documents)

Enhanced message templates for common scenarios

Advanced group management features

Contact management (add/remove contacts)

Enhanced error handling and recovery

Contributing

Fork the repository

Create a feature branch

Commit your changes

Push to your branch

Create a Pull Request

Please ensure your PR:

Follows the existing code style

Includes appropriate tests

Updates documentation as needed

Describes the changes in detail

Dependencies

WhatsApp Web.js

This project uses whatsapp-web.js, an unofficial JavaScript client library for WhatsApp Web that connects through the WhatsApp Web browser app. For more information, visit the whatsapp-web.js GitHub repository.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Logging

WhatsApp Web MCP includes a robust logging system built with Winston. The logging system provides:

Multiple log levels (error, warn, info, http, debug)

Console output with colorized logs

HTTP request/response logging for API endpoints

Structured error handling

Environment-aware log levels (development vs. production)

All logs directed to stderr when running in MCP command mode

Log Levels

The application supports the following log levels, in order of verbosity:

error - Critical errors that prevent the application from functioning

warn - Warnings that don't stop the application but require attention

info - General information about application state and events

http - HTTP request/response logging

debug - Detailed debugging information

Configuring Log Level

You can configure the log level when starting the application using the --log-level or -l flag:

Or when using the global installation:

Command Mode Logging

When running in MCP command mode (--mode mcp --transport command), all logs are directed to stderr. This is important for command-line tools where stdout might be used for data output while stderr is used for logging and diagnostics. This ensures that the MCP protocol communication over stdout is not interfered with by log messages.

Test Environment

In test environments (when NODE_ENV=test or when running with Jest), the logger automatically adjusts its behavior to be suitable for testing environments.