WhatsApp Web MCP

Name: WhatsApp Web MCP
Author: pnizer

@pnizer

Repository

About WhatsApp Web MCP

WhatsApp Web MCP Server

#mcp #whatsapp

Basic information

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "wweb-mcp": {
      "command": "docker",
      "args": [
        "build",
        ".",
        "-t",
        "wweb-mcp:latest"
      ]
    }
  }
}

Tools

Check WhatsApp client connection status

Send messages to WhatsApp contacts

Search for contacts by name or number

Retrieve messages from a specific chat

Get a list of all WhatsApp chats

Create a new WhatsApp group

Add participants to an existing group

Retrieve messages from a group

Send a message to a group

Search for groups by name, description, or member names

Get detailed information about a specific group

Download media from a message

Send a media message to a WhatsApp contact

Overview

What is 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.

How to use WhatsApp Web MCP?

Install globally via npm or use with npx. Alternatively, build with Docker. Run in one of three modes: WhatsApp API Server (REST), MCP Server (standalone direct connection), or MCP Server as API client (connects to the WhatsApp API Server). Configure using command-line options for transport (SSE or command), ports, and authentication. Scan a QR code with your WhatsApp mobile app for authentication. For Claude Desktop integration, add the appropriate NPX or Docker configuration including the API key.

Key features of WhatsApp Web MCP

Send and receive messages to contacts and groups
Search and manage contacts and groups
Retrieve message history from chats and groups
Download and send media files (via URL or local file)
Webhook support for incoming messages with filters
REST API and MCP protocol access to WhatsApp

Use cases of WhatsApp Web MCP

Automate customer support or broadcast messaging via AI
Manage group memberships and send group messages programmatically
Integrate WhatsApp with AI assistants (e.g., Claude) for conversational workflows
Build custom dashboards or scripts that interact with WhatsApp chats

FAQ from WhatsApp Web MCP

Is WhatsApp Web MCP safe for production use?

No. The README explicitly states the tool is for testing purposes only and should not be used in production environments. It also notes that WhatsApp does not allow bots or unofficial clients, so using it may result in account blocking.

What authentication methods are available?

Two strategies: local (recommended) scans the QR code once and persists credentials between sessions; none requires scanning the QR code on each startup and is suitable for testing.

Can I receive incoming WhatsApp messages?

Yes. You can configure a webhook by creating a webhook.json file in the authentication data directory. The webhook supports filtering by allowed numbers, private messages, and group messages.

How do I connect WhatsApp Web MCP to Claude Desktop?

First, start the WhatsApp API server and note the API key from the logs. Then add an MCP server entry in your Claude Desktop configuration using either npx (with --mcp-mode api and the API key) or Docker (mounting a volume for authentication data).

What are the runtime and transport requirements?

The tool requires Node.js (run via npm/npx) or Docker. It supports two MCP transport modes: sse (HTTP server) and command (stdio). The WhatsApp API server uses port 3001 by default, and the SSE server uses port 3002.