# WhatsApp Web MCP Server [Health: Active]

**Category:** 💬 Communication  
**Repository:** https://github.com/mario-andreschak/mcp-whatsapp-web  
**GitHub Stars:** 29  
**npm Downloads (last month):** 254  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/whatsapp-web-mcp-server

## Description
MCP server for WhatsApp via whatsapp-web.js: send/receive messages, media, chats, groups, contacts

## Tools
Capabilities this server exposes over MCP:

- **get_qr_code** — Get the QR code for WhatsApp Web authentication
- **check_auth_status** — Check if you're currently authenticated with WhatsApp
- **logout** — Log out from WhatsApp and clear the current session
- **search_contacts** — Search for contacts by name or phone number
- **get_contact** — Get information about a specific contact
- **list_chats** — List available chats with metadata
- **get_chat** — Get information about a specific chat
- **get_direct_chat_by_contact** — Find a direct chat with a specific contact
- **list_messages** — Retrieve messages with optional filters
- **get_message** — Get a specific message by ID
- **send_message** — Send a text message to a chat
- **send_file** — Send a file (image, video, document) to a chat
- **send_audio_message** — Send an audio message (voice note)
- **download_media** — Download media from a message

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "whatsapp-web-mcp-server": {
    "command": "npx",
    "args": ["-y","mcp-whatsapp-web"]
  }
}
```

## Documentation

## What WhatsApp Web MCP Server MCP server does

WhatsApp Web MCP Server MCP server gives an MCP client access to a WhatsApp account through a TypeScript service. It can search contacts, inspect chats and messages, retrieve message details, and locate direct conversations. Agents can send text, images, videos, documents, and audio messages, as well as download media attached to messages.

The default backend uses whatsapp-web.js and a persistent LocalAuth profile. An optional Baileys backend uses a WebSocket-based connection instead of a browser. Both backends expose the same MCP interface for the supported contact, chat, message, media, and authentication operations, although their stored sessions and message identifiers are separate.

## How it works

Authentication starts through the MCP interface. Use `get_qr_code` to obtain a QR code for WhatsApp Web, or use the pairing-code flow where available. `check_auth_status` reports the current authentication state, and `logout` ends the session and clears its stored authentication data.

The server can communicate over stdio, which is the default when starting it normally, or over Streamable HTTP. It can also expose both transports from one process by setting an HTTP port, or run in HTTP-only mode with the relevant command-line option. HTTP clients may optionally use the documented OAuth flow.

## Setup and configuration

Node.js 22 or newer, plus npm or yarn, is required. The default web.js backend can use Google Chrome or Microsoft Edge; Puppeteer's bundled Chromium can handle other operations. The Baileys backend does not need a browser, but it requires its optional dependencies and the native `better-sqlite3` module.

Run the packaged command with `npx mcp-whatsapp-web`, or clone the repository, install dependencies, build the project, and start it with `npm start`. The first authentication must be completed after startup. A persistent session directory should be kept private and excluded from version control.

Set `WHATSAPP_BACKEND=baileys` to select Baileys and provide a separate `BAILEYS_SESSION_DIR` when needed. The default `webjs` backend uses its own session directory, which can be moved with `WHATSAPP_SESSION_DIR`. Browser location, headless mode, sandbox behavior, logging, and the FFmpeg binary can also be configured through the documented environment variables. FFmpeg is bundled automatically unless `FFMPEG_PATH` overrides it.

## Tools and capabilities

The available tools cover these operations:

- Authenticate, check status, request access, and log out.
- Search contacts by name or phone number and retrieve contact information.
- List chats, inspect a chat, or find a direct chat for a contact.
- List messages with filters and retrieve an individual message by ID.
- Send text, files, and audio voice notes to chats.
- Download media from messages.

Voice-note input must be a local file or base64 data. FFmpeg converts it to mono Opus/Ogg before sending. The server also supports media such as images, videos, and documents.

## Limitations and notes

WhatsApp automation without the Meta Business API is against WhatsApp's Terms of Service. Account owners are responsible for their use of the server, and WhatsApp may flag or restrict an account.

Baileys sessions cannot reuse web.js browser profiles, and only one running server should own a given Baileys session directory. Baileys stores credentials, contacts, chats, and messages locally in its session database. History synchronization may take time and may not provide a complete archive, so local results should not be treated as a guaranteed full account history.

Message IDs are backend-specific and should be treated as opaque values. IDs from web.js cannot be reused with Baileys. The Baileys backend is opt-in and pinned to a release candidate, so upstream authentication and message-format changes should be reviewed before upgrading.

_Full upstream README: https://allmcps.com/mcp/whatsapp-web-mcp-server/readme_