Log inSubmit server
WhatsApp Web MCP Server logo

WhatsApp Web MCP Server

Connect AI assistants to WhatsApp Web for contacts, chats, messages, authentication, and media handling.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install WhatsApp Web MCP Server

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "whatsapp-web-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-whatsapp-web"
      ]
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

We couldn’t confirm it starts correctly

We ran the install command but it didn't respond within our test window — this can mean a slow first-time install rather than a real problem.

npx -y mcp-whatsapp-web

No response to initialize.

This is an experimental automated check and can have false negatives — missing environment variables, a slow cold install, etc. It doesn’t necessarily mean something’s wrong. Last checked 7d ago.

Overview

WhatsApp Web MCP Server MCP server connects AI assistants to WhatsApp through whatsapp-web.js, with an optional Baileys backend. It exposes MCP tools for authentication, contacts, chats, messages, groups, and media, including sending text, files, and audio. The server supports stdio and Streamable HTTP transports and is suitable when an agent needs to search or manage a personal WhatsApp account. WhatsApp automation without the Meta Business API may violate WhatsApp's Terms of Service and can result in account restrictions.

Use cases

  • Search personal WhatsApp contacts and conversations
  • Read filtered messages and attached media
  • Send text or media to individual and group chats
  • Authenticate a WhatsApp session through an MCP client

Key features

  • WhatsApp Web contact, chat, and message access
  • Text, file, media, and voice-note sending
  • QR-code and pairing-code authentication
  • Optional Baileys browserless backend
  • Stdio and Streamable HTTP transports

Tools14

What WhatsApp Web MCP Server lets your agent do. Expand a tool for its parameters.

Self-reported~183 tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 2d ago

Recent health check succeeded.

6/6 checks healthy over the last 34d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 6d ago via OSV.dev · mcp-whatsapp-web (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars29Stargazers on the source repository.
npm downloads254Package downloads in the last 30 days.
Last commit1mo agoMost recent push to the default branch.
Install checkInconclusiveDidn't respond in our test window — often a slow first install.
Tools exposed14Callable tools this server registers over MCP.
Directory activity1 viewsConfig copies, upvotes, and views on AllMCPs.

How WhatsApp Web MCP Server works

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.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about WhatsApp Web MCP Server

WhatsApp Web MCP Server is an MCP server that connects AI assistants to WhatsApp through whatsapp-web.js by default, with an optional Baileys backend. Its main tools authenticate accounts, search contacts, inspect chats and messages, send text or media, send audio notes, and download message media.

Install it with `npx mcp-whatsapp-web`, or clone the repository, run `npm install`, build with `npm run build`, and start it with `npm start`. Node.js 22 or newer is required. After startup, authenticate through the `get_qr_code` tool.

Authenticate with the `get_qr_code` tool by scanning the displayed QR code in WhatsApp Web. The server also supports a pairing-code flow, including the `request_pairing_code` tool and the `WHATSAPP_PAIRING_PHONE_NUMBER` startup option.

The README explicitly documents stdio integration with Claude Desktop or similar applications, but does not specifically name Cursor.

Related MCP servers

All in Communication All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewWhatsApp Web MCP Server AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/whatsapp-web-mcp-server?style=directory)](https://allmcps.com/mcp/whatsapp-web-mcp-server)
HTML Embed
<a href="https://allmcps.com/mcp/whatsapp-web-mcp-server"><img src="https://allmcps.com/api/badge/whatsapp-web-mcp-server?style=directory" alt="WhatsApp Web MCP Server on AllMCPs" /></a>