WhatsApp Web / Personal MCP (was-whatsapp-web-mcp)

A self-contained, cross-platform Model Context Protocol (MCP) server for personal and business WhatsApp accounts via terminal QR code pairing. Built on pure WebSockets via Baileys (zero Chromium/Puppeteer overhead). Exposes 4 tools allowing AI coding assistants (Claude Desktop, Cursor, Antigravity, VS Code, Zed, etc.) to send messages, forward media, verify phone numbers, and check status using your linked WhatsApp number. Built by Web Analytics Solution.

Prerequisites

Related MCP server: whatsapp-mcp-server

Quick Start — 3 Steps

Step 1 — Pair via Terminal QR Code

Run the interactive authorization command in your terminal:

npx -y github:mnsmasum62786/was-whatsapp-web-mcp auth

1. A QR code will display directly in your terminal.

2. Open WhatsApp on your phone.

3. Tap Settings (or the 3 dots on Android) > Linked Devices > Link a Device.

4. Point your camera at the terminal QR code to scan it.

5. The session will be encrypted and saved locally at ~/.was-whatsapp-web-mcp/session/.

Step 2 — Add to Your AI Client

Add the following configuration to your AI client's MCP configuration JSON file:

{
  "mcpServers": {
    "WhatsApp Web MCP": {
      "command": "npx",
      "args": ["-y", "github:mnsmasum62786/was-whatsapp-web-mcp"]
    }
  }
}

Configuration File Locations by Client:

• Claude Desktop (Mac): ~/Library/Application Support/Claude/claude_desktop_config.json

• Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json

• Cursor: ~/.cursor/mcp.json (or via Cursor Settings -> MCP)

• Google Antigravity / Windsurf: ~/.gemini/antigravity/mcp.json or ~/.codeium/windsurf/mcp_config.json

What You Can Ask the AI

Messaging & Notifications

• "Send a WhatsApp message to +15551234567 saying: 'Hey, I am testing my AI agent on WhatsApp!'."

• "Send an image from https://example.com/chart.png to +15551234567 with caption 'Monthly Report'."

• "Send a PDF contract from https://example.com/contract.pdf to group 120363024849202@g.us."

Validation & Status

• "Check if +15551234567 is registered on WhatsApp."

• "Show my current WhatsApp connection status and linked phone number."

All Tools (4 Total)

CLI Commands

You can run these commands directly via npx -y github:mnsmasum62786/was-whatsapp-web-mcp <command>:

• auth — Display QR code in terminal and pair with your WhatsApp phone.

• status — Show whether your WhatsApp session is linked and file paths.

• logout — Delete the local session directory (~/.was-whatsapp-web-mcp/).

• help — Print command line usage.

Troubleshooting

1. "WhatsApp Web MCP — not configured yet"

• Cause: The server was started before pairing your device.

• Fix: Open your terminal and run npx -y github:mnsmasum62786/was-whatsapp-web-mcp auth.

2. "WhatsApp connection timed out (15s)"

• Cause: Your phone might be offline or disconnected from Wi-Fi/cellular data.

• Fix: Open WhatsApp on your phone to refresh connection and retry.

3. Windows PowerShell Execution Policy Error

If you see an error like npx.ps1 cannot be loaded because running scripts is disabled:

• Fix: Run the following command in PowerShell:

  Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

4. Cache Issues after Updates

To force clear the npx cache and download the latest release:

• Windows (PowerShell):

  Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache" -ErrorAction SilentlyContinue
  npm cache clean --force

• Mac / Linux:

  rm -rf ~/.npm/_npx
  npm cache clean --force

License

MIT License. Built by Web Analytics Solution.