WhatsApp Web MCP Server

Official

by mario-andreschak · TypeScript

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

Send and receive WhatsApp messages, media, and manage chats and contacts.

whatsappmessagingchat automationmedia sharinggroupscontactswhatsapp web

README.md11 KBView on GitHub

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
WhatsApp Web Integration: Uses whatsapp-web.js for direct connection to WhatsApp Web
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 MCP_HTTP_PORT to additionally expose http://127.0.0.1:<port>/mcp, or run HTTP-only with --http)
Flexible Authentication: QR code (as an MCP image tool), pairing code (request_pairing_code tool, or automatically printed to stderr at startup via WHATSAPP_PAIRING_PHONE_NUMBER), and an optional OAuth flow for HTTP clients (MCP_OAUTH=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:

TypeScript MCP Server: Implements the Model Context Protocol to provide standardized tools for AI assistants to interact with WhatsApp
WhatsApp Web Service: Connects to WhatsApp Web via whatsapp-web.js, handles authentication, and manages message sending/receiving
Tool Implementations: Provides various tools for contacts, chats, messages, media, and authentication

Prerequisites

Node.js >= 20.0.0
npm or yarn
Google Chrome or Microsoft Edge (auto-detected; only needed for sending videos/GIFs — everything else works with the Chromium that puppeteer downloads automatically)

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

Manual Installation

Clone this repository

bash

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

Install dependencies
bash
```
npm install
```
Build the project
bash
```
npm run build
```
Configure environment variables (optional)

Copy the example environment file and modify as needed:
bash
```
cp .env.example .env
```
You can adjust logging levels, pin the WhatsApp Web version, or override the auto-detected browser (BROWSER_EXECUTABLE_PATH) and ffmpeg binary (FFMPEG_PATH) if needed. WHATSAPP_HEADLESS=false shows the browser window (debugging aid), and WHATSAPP_SESSION_DIR relocates the session/browser-profile directory (useful for running multiple instances or isolated test runs).

Installation with FLUJO

FLUJO provides a streamlined installation process:

Navigate to the MCP section in FLUJO
Click "Add Server"
Copy and paste this GitHub repository URL: https://github.com/mario-andreschak/mcp-whatsapp-web
Click "Parse", "Clone, "Install", "Build" and "Update Server"

FLUJO will automatically handle the cloning, dependency installation, and building process for you.

Usage

Starting the MCP Server

bash

npm start

This will start the MCP server using stdio transport by default, which is suitable for integration with Claude Desktop or similar applications.

Important: After starting the server for the first time, you must authenticate with WhatsApp by using the get_qr_code tool and scanning the QR code with your phone. See the Authentication section for detailed instructions.

Development Mode

bash

npm run dev

This starts the server in development mode with TypeScript watch mode and automatic server restarts.

Debugging with MCP Inspector

bash

npm run debug

This launches the MCP Inspector tool, which provides a web interface for testing and debugging your MCP server. The inspector allows you to:

View all available tools and their schemas
Execute tools directly and see their responses
Test your server without needing to connect it to an AI assistant
Debug tool execution and inspect responses

Connecting to Claude Desktop

Create a configuration file for Claude Desktop:

json

{
  "mcpServers": {
    "whatsapp": {
      "command": "node",
      "args": [
        "PATH_TO/dist/index.js"
      ]
    }
  }
}

Replace PATH_TO with the absolute path to the repository.

Save this as claude_desktop_config.json in your Claude Desktop configuration directory:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json
Restart Claude Desktop

Connecting to Cursor

Create a configuration file for Cursor:

json

{
  "mcpServers": {
    "whatsapp": {
      "command": "node",
      "args": [
        "PATH_TO/dist/index.js"
      ]
    }
  }
}

Replace PATH_TO with the absolute path to the repository.

Save this as mcp.json in your Cursor configuration directory:
- macOS/Linux: ~/.cursor/mcp.json
- Windows: %USERPROFILE%\.cursor\mcp.json
Restart Cursor

Authentication

The first time you run the server, you'll need to authenticate with WhatsApp:

Start the MCP server
Important: You must use the get_qr_code tool to generate a QR code
- In Claude or other AI assistants, explicitly ask to "use the get_qr_code tool to authenticate WhatsApp"
- The assistant will call this tool and display the QR code image
Scan the QR code with your WhatsApp mobile app
- Open WhatsApp on your phone
- Go to Settings > Linked Devices > Link a Device
- Point your phone camera at the QR code displayed

Your session will be saved locally in the whatsapp-sessions directory and will be reused automatically on subsequent runs. If you don't authenticate using the QR code, you won't be able to use any WhatsApp functionality.

Authentication Status and Logout

You can check your current authentication status and manage your session:

Use the check_auth_status tool to verify if you're currently authenticated
If you need to authenticate with a different WhatsApp account or re-authenticate:
1. Use the logout tool to log out from your current session
2. Then use the get_qr_code tool to authenticate with a new QR code

This is particularly useful when:

You want to switch between different WhatsApp accounts
Your session has expired or been invalidated
You're experiencing connection issues and need to re-authenticate

Available MCP Tools

Authentication

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

Contacts

search_contacts- Search for contacts by name or phone number
get_contact- Get information about a specific contact

Chats

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

Messages

list_messages- Retrieve messages with optional filters
get_message- Get a specific message by ID
send_message- Send a text message to a chat

Media

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

Browser Process Management

This MCP server uses Puppeteer to control Chrome browsers for WhatsApp Web connectivity. The server includes a robust browser process management system to prevent orphaned Chrome processes.

Automatic Browser Cleanup

The server automatically:

Tracks Chrome browser processes using a PID tracking system
Cleans up orphaned processes on startup
Properly closes browser processes during shutdown
Maintains a record of browser PIDs in .chrome-pids.json

Manual Browser Cleanup

If you notice orphaned Chrome processes that weren't automatically cleaned up, you can use the included cleanup utility:

bash

npm run cleanup-browsers

This utility will:

Scan for Chrome processes that might be related to WhatsApp Web
Display a list of potentially orphaned processes
Ask for confirmation before terminating them
Clean up the PID tracking file

Development

Project Structure

src/index.ts- Entry point
src/server.ts- MCP server implementation
src/services/whatsapp.ts- WhatsApp Web service
src/tools/- Tool implementations for various WhatsApp features
src/types/- TypeScript type definitions
src/utils/- Utility functions

Scripts

npm run build- Build the TypeScript code
npm run dev- Run in development mode with watch
npm run lint- Run ESLint
npm run format- Format code with Prettier
npm run cleanup-browsers- Detect and clean up orphaned Chrome browser processes
npm test - Run the unit test suite (fast, no browser needed)
npm run test:watch - Run unit tests in watch mode during development
npm run test:e2e - Build, then run end-to-end tests (spawns the real server incl. a headless browser)

Troubleshooting

Authentication Issues

If the QR code doesn't appear, try restarting the server
If you're already authenticated, no QR code will be shown (use check_auth_status to verify)
If you need to re-authenticate, use the logout tool first, then request a new QR code
WhatsApp limits the number of linked devices; you may need to remove an existing device
If you receive a message saying "No QR code is currently available," but you're already authenticated, this is normal behavior - use check_auth_status to confirm your authentication status

Connection Issues

Make sure you have a stable internet connection
If the connection fails, try restarting the server
Check the logs for detailed error messages

Browser Process Issues

If you notice high CPU usage or memory consumption, there might be orphaned Chrome processes
Run npm run cleanup-browsers to detect and clean up orphaned processes
If the server crashes frequently, check for orphaned processes and clean them up
On Windows, you can also use Task Manager to look for multiple Chrome processes with "headless" in the command line
On Linux/macOS, use ps aux | grep chrome to check for orphaned processes

License

MIT

This project is a TypeScript port of the original whatsapp-mcp by lharries.

Install

Configuration

Environment variables

LOG_LEVELdefault info

Log level for the log file (logs/mcp-whatsapp.log)

LOG_STDERR_LEVELdefault warn

Log level for stderr (visible in most MCP client logs)

WHATSAPP_HEADLESS

Set to false to show the browser window instead of running headless (debugging aid)

BROWSER_EXECUTABLE_PATH

Browser executable. Chrome and Edge are auto-detected in their standard install locations; set this only to use a specific browser. A real Chrome/Edge is required for sending videos and GIFs.

WHATSAPP_SESSION_DIR

Where the WhatsApp session (browser profile) is stored (default: <working directory>/whatsapp-sessions)

WHATSAPP_PAIRING_PHONE_NUMBER

Phone number pairing: when set (international, symbol-free format, e.g. 4915112345678), an 8-character pairing code is logged to stderr on startup instead of relying on the QR code

FFMPEG_PATH

Path to an ffmpeg binary (only needed to override the ffmpeg installed automatically via the ffmpeg-static npm package)

WA_WEB_VERSION

Pin the WhatsApp Web version. Only set this if a WhatsApp-side update breaks the client.

HEALTH_CHECK_INTERVAL_MSdefault 60000

Connection health check interval in milliseconds (<=0 disables)

TOOL_READY_TIMEOUT_MSdefault 45000

How long tool calls wait for the WhatsApp client to become ready before erroring

MCP_HTTP_PORT

When set, additionally exposes the MCP endpoint at http://127.0.0.1:<port>/mcp (Streamable HTTP) from the same process

MCP_HTTP_HOSTdefault 127.0.0.1

Bind address for the HTTP endpoint (do not expose publicly; the endpoint controls your personal WhatsApp account)

MCP_OAUTH

Enable OAuth for the HTTP endpoint: /mcp requires a bearer token and clients authenticate via a browser page showing the WhatsApp QR code / pairing form

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "mcp-whatsapp-web": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-whatsapp-web@1.1.0"
      ],
      "env": {
        "LOG_LEVEL": "info",
        "LOG_STDERR_LEVEL": "warn",
        "WHATSAPP_HEADLESS": "<YOUR_WHATSAPP_HEADLESS>",
        "BROWSER_EXECUTABLE_PATH": "<YOUR_BROWSER_EXECUTABLE_PATH>",
        "WHATSAPP_SESSION_DIR": "<YOUR_WHATSAPP_SESSION_DIR>",
        "WHATSAPP_PAIRING_PHONE_NUMBER": "<YOUR_WHATSAPP_PAIRING_PHONE_NUMBER>",
        "FFMPEG_PATH": "<YOUR_FFMPEG_PATH>",
        "WA_WEB_VERSION": "<YOUR_WA_WEB_VERSION>",
        "HEALTH_CHECK_INTERVAL_MS": "60000",
        "TOOL_READY_TIMEOUT_MS": "45000",
        "MCP_HTTP_PORT": "<YOUR_MCP_HTTP_PORT>",
        "MCP_HTTP_HOST": "127.0.0.1",
        "MCP_OAUTH": "<YOUR_MCP_OAUTH>"
      }
    }
  }
}