WhatsApp MCP Server

A Model Context Protocol (MCP) server for WhatsApp using the Baileys library. Connect using QR code authentication - just like WhatsApp Web!

Features

• QR Code Authentication - Scan with your phone to connect (like WhatsApp Web)
• Persistent Sessions - Credentials stored locally, no re-scan needed
• Personal WhatsApp - Use your regular WhatsApp number, no Business API needed
• Full Messaging - Text, images, videos, audio, documents, locations, contacts
• Groups - Send to groups, get group info
• Reactions & Polls - React to messages, create polls
• Typing Indicators - Show/hide typing status
• Read Receipts - Mark messages as read

Prerequisites

• Node.js 18+
• A smartphone with WhatsApp installed
• Same phone number you want to use

Installation

cd /path/to/whatsapp-mcp
npm install
npm run build

Configuration

Add to your .mcp.json or Claude Desktop config:

{
  "mcpServers": {
    "whatsapp": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/whatsapp-mcp/build/index.js"],
      "env": {
        "WHATSAPP_AUTH_DIR": "/path/to/custom/auth/dir"
      }
    }
  }
}

Environment Variables:

• WHATSAPP_AUTH_DIR - Custom directory for credentials (default: ~/.whatsapp-mcp/auth/)

First Time Setup

1. Start the MCP server
2. Call the connect tool
3. A browser window will open with the QR code (like Teams/Outlook device flow)
4. Open WhatsApp on your phone → Settings → Linked Devices → Link a Device
5. Scan the QR code shown in the browser
6. The browser will show "Connected!" and close automatically
7. You're connected! Credentials are saved for future sessions.

Available Tools

Connection

| Tool | Description | |------|-------------| | get_connection_status | Check connection status and logged-in user | | connect | Connect to WhatsApp (shows QR if needed) | | disconnect | Disconnect from WhatsApp | | logout | Logout and clear credentials |

Messaging

| Tool | Description | |------|-------------| | send_text_message | Send a text message | | send_image | Send an image | | send_video | Send a video | | send_audio | Send audio/voice note | | send_document | Send a document | | send_location | Send a location | | send_contact | Send a contact card | | send_reaction | React to a message | | send_poll | Create a poll |

Typing & Read

| Tool | Description | |------|-------------| | send_typing | Show typing indicator | | stop_typing | Stop typing indicator | | mark_as_read | Mark messages as read |

Groups

| Tool | Description | |------|-------------| | get_groups | List all groups | | get_group_info | Get group details |

Presence

| Tool | Description | |------|-------------| | set_presence | Set online/offline status |

Phone Number Format

Use phone numbers with country code, no symbols:

• ✅ 919876543210 (India)
• ✅ 14155551234 (USA)
• ❌ +91 98765 43210
• ❌ 09876543210

For groups, use the group ID (e.g., 1234567890-1234567890)

Usage Examples

Send a message

Send "Hello from LIFEOSAI!" to 919876543210

Send an image

Send image from https://example.com/image.jpg to 919876543210 with caption "Check this!"

Send to a group

Send "Team meeting at 3pm" to group 1234567890-1234567890

Create a poll

Create poll "What's for lunch?" with options ["Pizza", "Burger", "Salad"] in group 1234567890-1234567890

Security Notes

• Credentials are stored locally in ~/.whatsapp-mcp/auth/
• Never share your auth folder with others
• Use logout tool to clear credentials if needed
• This uses the same protocol as WhatsApp Web

Troubleshooting

QR code not showing in browser

• Check if browser opened (look for http://localhost:9876)
• Try opening http://localhost:9876 manually
• Ensure you're calling connect tool

Connection timeout

• QR code expires after ~1 minute
• Call connect again for new QR

"Logged out" error

• WhatsApp session was terminated from phone
• Call logout then connect for fresh QR

Messages not sending

• Check connection status with get_connection_status
• Verify phone number format (country code, no symbols)
• Ensure recipient has WhatsApp

How It Works

This MCP uses Baileys, a reverse-engineered WhatsApp Web API. It connects using the same protocol as the official WhatsApp Web client:

1. Authentication: QR code links to your phone (multi-device)
2. Encryption: End-to-end encrypted like regular WhatsApp
3. Session: Persisted locally, reconnects automatically

License

MIT

Author

Suhail [email protected]