Self-Hosting Guide

Deploy your own instance on Cloudflare Workers with full control over your data and credentials.

Not technical? You don't need to self-host. The hosted version works out of the box with zero setup. Self-hosting is for developers who want full control.

Prerequisites

Step 1: Clone and Install

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

Step 2: Create Cloudflare Resources

Login to Cloudflare

npx wrangler login

This opens your browser. Sign in and authorize Wrangler.

Create D1 Database

npx wrangler d1 create whatsapp-mcp-db

Copy the database_id from the output.

Create KV Namespace

npx wrangler kv namespace create CACHE

Copy the id from the output.

Update wrangler.toml

Open wrangler.toml and replace the placeholder IDs:

# Replace YOUR_KV_NAMESPACE_ID with the KV id
[[kv_namespaces]]
binding = "CACHE"
id = "YOUR_KV_NAMESPACE_ID"

# Replace YOUR_D1_DATABASE_ID with the D1 database_id
[[d1_databases]]
binding = "DB"
database_name = "whatsapp-mcp-db"
database_id = "YOUR_D1_DATABASE_ID"

Step 3: Get WhatsApp API Credentials

1

Create a Meta Developer App

Go to developers.facebook.com/apps > "Create App" > Business type. Name it anything (avoid "WhatsApp" in the name — Meta blocks it). Select "Connect with customers via WhatsApp".

2

Get API credentials

In your app dashboard, go to WhatsApp > API Setup. You'll see:

  • Temporary Access Token (expires in 24h)
  • Phone Number ID (e.g., 1078241805365049)
  • WhatsApp Business Account ID (e.g., 1833125214038271)
3

For a permanent token (recommended)

Go to Meta Business Settings > System Users > Create a System User (Admin) > Generate Token with whatsapp_business_messaging and whatsapp_business_management permissions.

Step 4: Set Secrets

# Required secrets
npx wrangler secret put WHATSAPP_ACCESS_TOKEN
npx wrangler secret put WHATSAPP_PHONE_NUMBER_ID
npx wrangler secret put WHATSAPP_BUSINESS_ACCOUNT_ID

# For webhook signature verification
npx wrangler secret put WHATSAPP_WEBHOOK_VERIFY_TOKEN
npx wrangler secret put META_APP_SECRET

# For billing (optional, only if you want paid tiers)
npx wrangler secret put LEMONSQUEEZY_WEBHOOK_SECRET
Each command will prompt you to paste the value. The value is stored securely and never shown again.

Step 5: Run Database Migrations

npx wrangler d1 execute whatsapp-mcp-db --remote --file=./schemas/d1-schema.sql

Step 6: Deploy

npx wrangler deploy

You'll see output like:

Uploaded whatsapp-mcp-server (5.18 sec)
Deployed whatsapp-mcp-server triggers (1.08 sec)
  https://whatsapp-mcp-server.YOUR_SUBDOMAIN.workers.dev
Your server is now live! Use the URL from the output in your Claude Desktop config.

Step 7: Configure Webhooks (Optional)

To receive incoming messages, set up webhooks in Meta:

1

Go to Meta Developer Portal

Your App > WhatsApp > Configuration > Webhooks

2

Set Webhook URL

https://YOUR-WORKER.workers.dev/webhook

3

Set Verify Token

Same value you used for WHATSAPP_WEBHOOK_VERIFY_TOKEN

4

Subscribe to messages

Check the messages field to receive incoming messages.

Development

# Run locally
npx wrangler dev

# Run tests (72 tests)
npm test

# Type check
npm run typecheck

Architecture

Claude / AI Assistant
       |
       v
Cloudflare Worker (Edge)
  - MCP Protocol (JSON-RPC)
  - Auth + API Keys + Tiers
  - Rate Limiting
       |
   +---+---+
   v       v
WhatsApp  Durable Objects
Cloud API (webhooks storage)
             |
         +---+---+
         v       v
        D1      KV
      (logs)  (cache)
View on GitHub Use Hosted Version