WhatsApp MCP Server

Server is running
Authentication Required
This API requires an API key for access.

About

A Model Context Protocol (MCP) server providing full access to WhatsApp messaging via the whatsmeow bridge. Read messages, search contacts, send texts, media, and voice messages.

API Key Access
To request an API key for this service, please contact:
bartosz.dariusz.majewski@gmail.com

API Endpoint

POST requests to: https://whatsapp.mcp.majewscy.tech/

Required HTTP Headers

x-api-key

Your server authentication key (contact us for access)

Test Your Connection

1. Check WhatsApp Status

curl -X POST https://whatsapp.mcp.majewscy.tech/ \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_SERVER_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get_whatsapp_status",
      "arguments": {}
    },
    "id": 1
  }'

2. List Available Tools

curl -X POST https://whatsapp.mcp.majewscy.tech/ \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_SERVER_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

Configuration Examples

Claude Code (.mcp.json)

{
  "mcpServers": {
    "whatsapp": {
      "type": "http",
      "url": "https://whatsapp.mcp.majewscy.tech/",
      "headers": {
        "x-api-key": "YOUR_SERVER_KEY"
      }
    }
  }
}

Available Tools

Status & Contacts

  • get_whatsapp_status - Check connection & auth status
  • search_contacts - Search contacts by name/phone

Messages

  • list_messages - Query messages with filters
  • get_recent_conversations - Recent chat overview
  • get_message_context - Context around a message

Chat Management

  • list_chats - List chats with metadata
  • get_chat - Get chat by JID
  • get_direct_chat_by_contact - Find DM by phone
  • get_contact_chats - All chats for a contact
  • get_last_interaction - Most recent message

Sending & Media

  • send_message - Send text message
  • send_file - Send image/video/document
  • send_audio_message - Send voice message
  • download_media - Download media from message

WhatsApp Setup

On first run, you need to scan a QR code to authenticate with WhatsApp:

  1. Call get_whatsapp_status to check if QR scan is needed
  2. Access the QR code at GET /qr (requires x-api-key header)
  3. Scan with your WhatsApp mobile app (Linked Devices)
  4. Session persists across restarts (~20 day expiry)

Common Errors

Invalid API Key

{"jsonrpc":"2.0","id":1,"error":{"code":-32001,"message":"Invalid API Key"}}

Solution: Check your x-api-key header value

Bridge Not Running

{"logged_in": false, "message": "WhatsApp service is currently unavailable."}

Solution: Check container logs, the Go bridge may need time to start

Health Check

GET /health - Returns server status (no authentication required)