WhatsApp Web MCP Server

Very Important

Automation of Whatsapp Messages without Meta (Business-)API is against WhatsApp' Terms of Service! You take full responsibility for everything you do with this MCP-Server. It is possible that your account will be flagged/restricted.

MCP WhatsApp Web (TypeScript)

A Model Context Protocol (MCP) server for WhatsApp Web, implemented in TypeScript. This project is a TypeScript port of the original whatsapp-mcp repository.

With this MCP server, you can:

• Search and read your personal WhatsApp messages (including media)
• Search your contacts
• Send messages to individuals or groups
• Send and receive media files (images, videos, documents, audio)

Features

• TypeScript Implementation: Fully typed codebase for better developer experience and code reliability
• Selectable WhatsApp Backend: Uses whatsapp-web.js by default, with an optional Baileys backend that runs without a browser
• MCP Server: Implements the Model Context Protocol for seamless integration with AI assistants
• Media Support: Send and receive images, videos, documents, and audio messages
• Multiple Transport Options: Supports stdio and Streamable HTTP transports — even both at once from a single process (start with stdio and set MCPHTTPPORT to additionally expose http://127.0.0.1:/mcp, or run HTTP-only with --http)
• Flexible Authentication: QR code (as an MCP image tool), pairing code (requestpairingcode tool, or automatically printed to stderr at startup via WHATSAPPPAIRINGPHONENUMBER), and an optional OAuth flow for HTTP clients (MCPOAUTH=true) where the browser authorization page shows the WhatsApp QR code — unlinking WhatsApp revokes tokens so clients automatically re-authenticate

Architecture

This MCP server consists of:

1. TypeScript MCP Server: Implements the Model Context Protocol to provide standardized tools for AI assistants to interact with WhatsApp
2. WhatsApp Backend: A shared service interface selects web.js/Puppeteer or Baileys/WebSocket, handles authentication, and manages message sending/receiving
3. Tool Implementations: Provides various tools for contacts, chats, messages, media, and authentication

Prerequisites

• Node.js >= 22.0.0 (Node 22 or 24 recommended for the Baileys SQLite dependency)
• npm or yarn
• For the default webjs backend: Google Chrome or Microsoft Edge (auto-detected; needed for video/GIF codec support; other operations can use Puppeteer's bundled Chromium)
• For baileys: install optional dependencies, including the native better-sqlite3 module. No Chrome, Edge, or Chromium is needed at runtime.

FFmpeg is bundled automatically via the ffmpeg-static npm package — no manual installation needed. You can point the FFMPEG_PATH environment variable at your own binary to override it.

Installation

npx

npx mcp-whatsapp-web

Manual Installation

1. Clone this repository

git clone https://github.com/mario-andreschak/mcp-whatsapp-web.git
   cd mcp-whatsapp-web

1. Install dependencies

npm install

1. Build the project

npm run build

1. Configure environment variables (optional)

Copy the example environment file and modify as needed:

cp .env.example .env

Shortened. The full README is on GitHub.