WhatsApp Business MCP Server

The most complete MCP Server for WhatsApp Business Cloud API.
43 tools | 8 modules | Hosted on Cloudflare Workers | Zero installation

Built by spirit122

What is this?

This MCP Server lets you control WhatsApp Business directly from Claude AI. Send messages, receive replies, manage templates, track analytics — all through natural language.

Example: Just tell Claude "Send a message to +56 9 1234 5678 saying the order is ready" and it does it.

Get Started in 3 Steps

Step 1: Choose Your Plan

Buy Pro: Click here to subscribe

Buy Enterprise: Click here to subscribe

Step 2: Get Your API Key

After purchasing, you will receive a license key via email from Lemonsqueezy. This is your API key.

You can also retrieve it at any time:

GET https://whatsapp-mcp-server.eosspirit.workers.dev/billing/api-key?email=YOUR_EMAIL

Step 3: Connect to Claude Desktop

1. Open Claude Desktop
2. Click the gear icon (Settings) > Developer > Edit Config
3. This opens claude_desktop_config.json. Paste the config below.
4. Restart Claude Desktop

Config file location:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

Free tier (no API key needed):

{
  "mcpServers": {
    "whatsapp": {
      "type": "url",
      "url": "https://whatsapp-mcp-server.eosspirit.workers.dev/mcp"
    }
  }
}

Pro / Enterprise (with API key):

{
  "mcpServers": {
    "whatsapp": {
      "type": "url",
      "url": "https://whatsapp-mcp-server.eosspirit.workers.dev/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY_HERE"
      }
    }
  }
}

That's it! Now just ask Claude to send messages, check analytics, or anything else.

All 35 Tools

Module 1: Messages (10 tools)

Module 2: Interactive Messages (5 tools) PRO

Module 3: Templates (5 tools)

Module 4: Media (3 tools)

Module 5: Webhooks (3 tools) PRO

Module 6: Business Profile (3 tools)

Module 7: WhatsApp Flows (2 tools) PRO

Module 8: Analytics (4 tools) PRO

Safety Tools (2 tools — all tiers)

Enterprise Safety Tools (3 tools) ENTERPRISE

Anti-Spam Protection

Every outbound message is checked by the built-in MessageGuard before sending. No bad prompt can turn into spam.

Protections by Tier

How It Works

1. Allowlist — Enable it with manage_allowlist to restrict who can receive messages. If enabled, only numbers on the list can be messaged.
2. Per-recipient rate limit — Max messages to the same number per hour. Prevents flooding a single contact.
3. Unique recipient limit — Max different numbers per hour. Prevents mass-messaging campaigns.
4. Content filter — Blocks messages matching known spam patterns (promotional language, chain messages).
5. Duplicate detection — Blocks sending the same message to the same number within a short window.

Quick Example

You: "Send a message to +1234567890 saying hello"
Claude: ❌ Blocked — recipient not in allowlist. Use manage_allowlist to add them.

You: "Add +1234567890 to my allowlist"
Claude: ✅ Added. Allowlist now has 1 number.

You: "Send a message to +1234567890 saying hello"
Claude: ✅ Message sent!

AI Auto-Reply (Enterprise) — WhatsApp Chatbot

Enterprise customers can enable AI-powered automatic replies to incoming WhatsApp messages. When a customer messages you, the server calls an AI provider to generate a response and sends it back automatically.

Supported AI Providers

Each client uses their own AI API key — you are not charged for AI calls.

How to Set Up Auto-Reply

Step 1: Get an API key from your preferred provider:

• Groq (free): console.groq.com → API Keys → Create
• OpenAI: platform.openai.com → API Keys
• Claude: console.anthropic.com → API Keys
• Gemini: aistudio.google.com/apikey
• DeepSeek: platform.deepseek.com → API Keys

Step 2: Configure auto-reply via Claude:

You: "Configure auto-reply with Groq. My API key is gsk_xxxxx.
      Use this system prompt: You are a friendly customer service agent
      for my online store. Answer questions about products, shipping,
      and returns in Spanish. Our website is https://mystore.com"

Claude: ✅ Auto-reply ENABLED with Groq (Llama 3.3 70B)

Step 3: That's it! Incoming WhatsApp messages will now get automatic AI responses.

Auto-Reply Tools (3 tools) ENTERPRISE

Features

• Conversation memory — the AI remembers previous messages per customer (configurable, up to 20 messages)
• Business hours — only auto-reply during work hours, with a custom off-hours message
• Per-recipient rate limit — max 20 auto-replies per customer per hour (configurable)
• Custom system prompt — tell the AI who it is, what it sells, how to respond
• Any model — use the default or specify a custom model name

Example Conversation

Customer: "Hola, cuánto cuesta?"
Bot: "Hola Ricardo, tenemos planes Free, Pro ($29 USD/mes) y
      Enterprise ($99 USD/mes). Visita https://mysite.com para más detalles."

Customer: "Tienen envío gratis?"
Bot: "Sí, el envío es gratuito en pedidos mayores a $50.
      ¿Te gustaría hacer un pedido?"

Why This Server vs Others?

Self-Hosting (Advanced)

If you want to host your own instance instead of using our hosted version:

Prerequisites

• Cloudflare account
• Meta Business Account
• WhatsApp Business API access
• Node.js 18+

Setup

# Clone the repository
git clone https://github.com/spirit122/whatsapp-mcp-server.git
cd whatsapp-mcp-server
npm install

# Create Cloudflare resources
wrangler d1 create whatsapp-mcp-db
wrangler kv namespace create CACHE
# Update wrangler.toml with the generated IDs

# Set your WhatsApp API secrets
wrangler secret put WHATSAPP_ACCESS_TOKEN
wrangler secret put WHATSAPP_PHONE_NUMBER_ID
wrangler secret put WHATSAPP_BUSINESS_ACCOUNT_ID
wrangler secret put WHATSAPP_WEBHOOK_VERIFY_TOKEN
wrangler secret put META_APP_SECRET

# Run database migrations
wrangler d1 execute whatsapp-mcp-db --remote --file=./schemas/d1-schema.sql

# Deploy
wrangler deploy

Webhook Setup (to receive messages)

1. Go to Meta Developer Portal > Your App > WhatsApp > Configuration
2. Set Webhook URL: https://YOUR-WORKER.workers.dev/webhook
3. Set Verify Token: same value as your WHATSAPP_WEBHOOK_VERIFY_TOKEN secret
4. Subscribe to: messages

Development

wrangler dev          # Run locally
npm test              # Run tests (72 tests)
npm run typecheck     # TypeScript check

API Endpoints

Architecture

Claude / AI Assistant
       |
       v
┌──────────────────────────────┐
│  Cloudflare Worker (Edge)    │
│  - MCP Protocol (JSON-RPC)   │
│  - Auth + API Keys + Tiers   │
│  - Rate Limiting             │
│  - Billing (Lemonsqueezy)    │
└──────────┬───────────────────┘
           |
     ┌─────┴──────┐
     v            v
┌─────────┐  ┌──────────────┐
│ WhatsApp│  │ Durable      │
│ Cloud   │  │ Objects      │
│ API     │  │ (webhooks)   │
└─────────┘  └──────────────┘
                   |
            ┌──────┴──────┐
            v             v
        ┌──────┐     ┌──────┐
        │  D1  │     │  KV  │
        │ logs │     │cache │
        └──────┘     └──────┘

FAQ

Q: Do I need my own WhatsApp Business API account?
A: For the hosted version, your API key gives you access to the shared test environment. For production with your own phone number, you'll need a Meta Business Account.

Q: How do I get my API key after purchase?
A: You receive it via email from Lemonsqueezy. You can also retrieve it anytime at:
https://whatsapp-mcp-server.eosspirit.workers.dev/billing/api-key?email=YOUR_EMAIL

Q: Can I cancel my subscription?
A: Yes, anytime through Lemonsqueezy. Your API key will be deactivated at the end of the billing period.

Q: What happens if my API key stops working?
A: Check that your subscription is active. If your payment failed, update your payment method in Lemonsqueezy.

Q: Is there a free tier?
A: Yes! 5 core tools are available for free with no API key needed. Just connect to the MCP endpoint.

Q: How does anti-spam protection work?
A: Every message goes through the MessageGuard which checks allowlists, per-recipient rate limits, unique recipient limits, and spam content patterns. Use manage_allowlist to control who can receive messages, and get_messaging_safety_status to check your current limits.

Q: Can someone use a bad prompt to send spam?
A: No. The free tier only allows 5 messages to 3 different numbers per hour. All tiers have spam pattern detection and per-recipient rate limiting. You can enable an allowlist so messages can only go to pre-approved numbers.

Q: Can I self-host this?
A: Yes, the code is open source (MIT). See the Self-Hosting section above.

Support

• Free tier: GitHub Issues
• Pro: Email support (included with subscription)
• Enterprise: Priority support with SLA

License

MIT - Built by spirit122