WhatsApp Web

by fyimail

3 stars
Not rated
GitHub

About

Connects AI systems to WhatsApp Web for sending messages, managing groups, searching contacts, and retrieving chat history through direct connection or API client modes.

Details

Author
fyimail
Repository
fyimail/whatsapp-mcp2
GitHub stars
3
License
MIT License
Categories
Communication, Other, Developer Tools, Design, AI, Community, Search, Infrastructure
Tags
#integration, #web

Jump to

- Create webhooks for incoming messages and other WhatsApp events
- Support for sending media files (images, audio, documents)
- Group chat management features
- Contact management (add/remove contacts)
- Message templates for common scenarios
- Enhanced error handling and recovery

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

  1. Download and install Highlight from highlightai.com/download
  2. Navigate to the plugins tab and select "Add Custom Plugin"
  3. Configure the plugin with the settings below
    Plugin Name WhatsApp Web
    Command (node, npx, python, etc.) npx
    Arguments
    • Argument 1 wweb-mcp
    • Argument 2 -m
    • Argument 3 mcp
    • Argument 4 -s
    • Argument 5 local
    • Argument 6 -c
    • Argument 7 api
    • Argument 8 -t
    • Argument 9 command
    • Argument 10 --api-base-url
    • Argument 11 http://localhost:3001/api
    • Argument 12 --api-key
    • Argument 13 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

    Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.

  4. Enable "Start Automatically" if you want the plugin to start when Highlight launches

From the repository

npm install -g .

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.

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

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

1. WhatsApp API Server: Standalone REST API server
2. MCP Server (Standalone): Direct connection to WhatsApp Web
3. 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

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

npm start -- --log-level=debug

Or when using the global installation:

wweb-mcp --log-level=debug

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

get_status

Check WhatsApp client connection status. Parameters: None

send_message

Send messages to WhatsApp contacts. Parameters: `number`: Phone number to send to, `message`: Text content to send

search_contacts

Search for contacts by name or number. Parameters: `query`: Search term to find contacts

get_messages

Retrieve messages from a specific chat. Parameters: `number`: Phone number to get messages from, `limit` (optional): Number of messages to retrieve

get_chats

Get a list of all WhatsApp chats. Parameters: None

create_group

Create a new WhatsApp group. Parameters: `name`: Name of the group, `participants`: Array of phone numbers to add

add_participants_to_group

Add participants to an existing group. Parameters: `groupId`: ID of the group, `participants`: Array of phone numbers to add

get_group_messages

Retrieve messages from a group. Parameters: `groupId`: ID of the group, `limit` (optional): Number of messages to retrieve

send_group_message

Send a message to a group. Parameters: `groupId`: ID of the group, `message`: Text content to send

search_groups

Search for groups by name, description, or member names. Parameters: `query`: Search term to find groups

get_group_by_id

Get detailed information about a specific group. Parameters: `groupId`: ID of the group to get

| Tool | Description | Parameters |
|------|-------------|------------|
| get_status | Check WhatsApp client connection status | None |
| send_message | Send messages to WhatsApp contacts | number: Phone number to send to<br>message: Text content to send |
| search_contacts | Search for contacts by name or number | query: Search term to find contacts |
| get_messages | Retrieve messages from a specific chat | number: Phone number to get messages from<br>limit (optional): Number of messages to retrieve |
| get_chats | Get a list of all WhatsApp chats | None |
| create_group | Create a new WhatsApp group | name: Name of the group<br>participants: Array of phone numbers to add |
| add_participants_to_group | Add participants to an existing group | groupId: ID of the group<br>participants: Array of phone numbers to add |
| get_group_messages | Retrieve messages from a group | groupId: ID of the group<br>limit (optional): Number of messages to retrieve |
| send_group_message | Send a message to a group | groupId: ID of the group<br>message: Text content to send |
| search_groups | Search for groups by name, description, or member names | query: Search term to find groups |
| get_group_by_id | Get detailed information about a specific group | groupId: ID of the group to get |

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

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

Linux

{
    "env": [],
    "args": [
        "wweb-mcp",
        "-m",
        "mcp",
        "-s",
        "local",
        "-c",
        "api",
        "-t",
        "command",
        "--api-base-url",
        "http://localhost:3001/api",
        "--api-key",
        "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
    ],
    "shell": false,
    "command": "npx"
}

Macos

{
    "env": [],
    "args": [
        "wweb-mcp",
        "-m",
        "mcp",
        "-s",
        "local",
        "-c",
        "api",
        "-t",
        "command",
        "--api-base-url",
        "http://localhost:3001/api",
        "--api-key",
        "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
    ],
    "shell": false,
    "command": "npx"
}

Windows

{
    "env": [],
    "args": [
        "/c",
        "npx",
        "wweb-mcp",
        "-m",
        "mcp",
        "-s",
        "local",
        "-c",
        "api",
        "-t",
        "command",
        "--api-base-url",
        "http://localhost:3001/api",
        "--api-key",
        "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
    ],
    "command": "cmd"
}

WhatsApp Web MCP

A powerful bridge between WhatsApp Web and AI models using the Model Context Protocol (MCP). This project enables AI models like Claude to interact with WhatsApp through a standardized interface, making it easy to automate and enhance WhatsApp interactions programmatically.

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.

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

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
No reviews yet — be the first

Sign in to leave a review

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

Install

Add to Claude Desktop or Cursor

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

More like this

Similar MCP servers you might find useful

Browse category

Sequential Thinking

Sequential Thinking is an MCP server that provides a tool for dynamic and reflective problem-solving through a structured, step-by-step thinking process. It is…

88.2k
Other

Filesystem

Filesystem is a Node.js server that implements the Model Context Protocol (MCP) for filesystem operations. It enables AI assistants to read, write, and manage…

88.1k
Other