Which integrations are available for this server?

Leverages the official Meta WhatsApp Cloud API to provide secure, production-ready business messaging capabilities, template management, and business profile updates. Provides comprehensive tools for sending text, media, and template messages, managing conversation history, and handling real-time webhook updates for incoming messages and delivery statuses.

How do I use whatsapp-mcp-server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@whatsapp-mcp-server Send 'Your order #12345 is ready for pickup' to +15550198765" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

whatsapp-mcp-server

by FredShred7

Overview Schema Related Servers Score Discussions

TypeScript

Remote

whatsapp-mcp-server

A production-ready Model Context Protocol (MCP) server that connects AI assistants like Claude to the WhatsApp Cloud API (Meta). Send messages, manage conversations, handle media, send template messages, and receive real-time webhooks — all through natural language.

Why this MCP server?

This is the only WhatsApp MCP server built on the official Meta WhatsApp Cloud API.

Most WhatsApp tools for developers rely on unofficial browser automation libraries (whatsapp-web.js) or reverse-engineered protocols (whatsmeow, Baileys). These approaches violate WhatsApp's Terms of Service and carry a real risk of account bans. This project is different.

	whatsapp-mcp-server (this project)	Unofficial libraries (`whatsapp-web.js`, `whatsmeow`, `Baileys`)
API type	✅ Official Meta WhatsApp Cloud API	❌ Unofficial / reverse-engineered
Account ban risk	✅ None — Meta-approved	⚠️ High — violates WhatsApp ToS
Account type	✅ WhatsApp Business account	Personal account only
Uptime reliability	✅ Meta SLA-backed infrastructure	❌ Breaks when WhatsApp updates
Scalability	✅ Business-grade, multi-agent ready	❌ Limited to one session
Template messages	✅ Full support	❌ Not available
Media handling	✅ Native Cloud API media endpoints	⚠️ Workarounds required
Webhook support	✅ Official Meta webhook events	❌ Polling / fragile listeners
Production use	✅ Built for production	❌ Recommended for personal/hobby use only
Long-term viability	✅ Stable, versioned API	❌ Depends on reverse engineering staying current

Bottom line: if you are building anything beyond a personal experiment — customer support, automated notifications, business workflows — use the official API. This server gives you that, packaged as a drop-in MCP server.

Features

Send all message types — text, images, videos, audio, documents, reactions
Template messages — send and list approved WhatsApp Business templates with full component support
Media management — upload, retrieve, and delete media files
Conversation history — in-memory store of recent conversations via webhook
Real-time webhooks — receive incoming messages and delivery status updates
Business profile — read and update your WhatsApp Business profile
Contact lookup — validate phone numbers against WhatsApp
Rate limit handling — automatic exponential backoff retry logic
Type-safe — fully typed TypeScript with Zod input validation
Docker ready — multi-stage Dockerfile and docker-compose included
Works without webhook — send-only mode with no webhook server required

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    AI Assistant (Claude)                      │
└──────────────────────────┬──────────────────────────────────┘
                           │ MCP Protocol (stdio)
                           │
┌──────────────────────────▼──────────────────────────────────┐
│                  whatsapp-mcp-server                         │
│                                                              │
│  ┌─────────────┐  ┌──────────────┐  ┌───────────────────┐  │
│  │  MCP Server │  │   Tools      │  │  WhatsApp Client  │  │
│  │  (stdio)    │◄─┤  messages    ├─►│  (Axios + retry)  │  │
│  │             │  │  contacts    │  └────────┬──────────┘  │
│  └─────────────┘  │  media       │           │              │
│                   │  templates   │           │ HTTPS        │
│  ┌─────────────┐  └──────────────┘           │              │
│  │  Webhook    │                             ▼              │
│  │  Server     │  ◄──── Incoming   ┌─────────────────────┐ │
│  │  (Express)  │       messages    │ WhatsApp Cloud API  │ │
│  └──────┬──────┘       & statuses  │  graph.facebook.com  │ │
└─────────│───────────────────────────┼─────────────────────┘ │
          │                           │                        │
          │ HTTP POST (Meta webhooks) │ HTTPS (send messages)  │
          │                           │                        │
     ┌────▼──────────────────────────▼──────────────┐
     │            WhatsApp Users                     │
     └────────────────────────────────────────────────┘

Webhook flow for incoming messages:
WhatsApp User → Meta Servers → POST /webhook → WhatsAppWebhook
→ in-memory conversation store → EventEmitter → MCP tools

Prerequisites

Node.js 20+ — download
Meta Developer Account — create one
WhatsApp Business App configured in Meta App Dashboard
Phone Number ID and Access Token from your WhatsApp app settings
(Optional) A public HTTPS URL for receiving webhooks (use ngrok for local dev)

Quick Start

Step 1 — Clone and install:

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

Step 2 — Configure credentials:

cp .env.example .env
# Edit .env with your WhatsApp credentials

Step 3 — Build:

npm run build

Step 4 — Add to Claude Desktop or Claude Code (see sections below)

Step 5 — Test it: Ask Claude: "Send a WhatsApp message to +15551234567 saying Hello from Claude!"

Configuration

All configuration is via environment variables. Copy .env.example to .env and fill in the values.

Variable	Required	Description
`WHATSAPP_PHONE_NUMBER_ID`	Yes	Your WhatsApp phone number ID (from Meta App Dashboard > WhatsApp > API Setup)
`WHATSAPP_ACCESS_TOKEN`	Yes	Permanent access token for your app (generate in Meta App Dashboard)
`WHATSAPP_WEBHOOK_VERIFY_TOKEN`	Webhook	Random secret string — must match what you enter in Meta App Dashboard
`WHATSAPP_BUSINESS_ACCOUNT_ID`	Optional	WhatsApp Business Account ID — required for listing phone numbers and templates
`WHATSAPP_API_VERSION`	Optional	WhatsApp Cloud API version (default: `v21.0`)
`WEBHOOK_PORT`	Optional	Port for incoming webhook server (default: off). Set to `3000` to enable
`WEBHOOK_PATH`	Optional	HTTP path for webhooks (default: `/webhook`)
`LOG_LEVEL`	Optional	Logging verbosity: `info` or `debug` (default: `info`)

Available Tools

Tool	Description	Key Parameters
`whatsapp_send_text`	Send a text message	`to`, `text`, `preview_url?`, `reply_to_message_id?`
`whatsapp_send_image`	Send an image with optional caption	`to`, `image_url`, `caption?`
`whatsapp_send_video`	Send a video with optional caption	`to`, `video_url`, `caption?`
`whatsapp_send_audio`	Send an audio message	`to`, `audio_url`
`whatsapp_send_document`	Send a document/file	`to`, `document_url`, `caption?`, `filename?`
`whatsapp_send_reaction`	React to a message with emoji	`to`, `message_id`, `emoji`
`whatsapp_mark_read`	Mark a message as read	`message_id`
`whatsapp_list_conversations`	List recent conversations (webhook required)	`limit?`
`whatsapp_get_conversation`	Get messages with a contact (webhook required)	`phone_number`, `limit?`
`whatsapp_get_message_status`	Get delivery/read status (webhook required)	`message_id`
`whatsapp_get_contact`	Validate a phone number on WhatsApp	`phone_number`
`whatsapp_get_business_profile`	Get your WhatsApp Business profile	—
`whatsapp_update_business_profile`	Update business profile info	`about?`, `address?`, `description?`, `email?`, `websites?`, `vertical?`
`whatsapp_upload_media`	Upload media from URL, get media ID	`media_url`, `mime_type`, `filename?`
`whatsapp_get_media_url`	Get temporary download URL for media	`media_id`
`whatsapp_delete_media`	Delete uploaded media	`media_id`
`whatsapp_send_template`	Send an approved template message	`to`, `template_name`, `language_code`, `components?`
`whatsapp_list_templates`	List available message templates	`limit?`

Usage with Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "whatsapp": {
      "command": "node",
      "args": ["/absolute/path/to/whatsapp-mcp-server/dist/index.js"],
      "env": {
        "WHATSAPP_PHONE_NUMBER_ID": "your_phone_number_id",
        "WHATSAPP_ACCESS_TOKEN": "your_access_token",
        "WHATSAPP_WEBHOOK_VERIFY_TOKEN": "your_verify_token",
        "WHATSAPP_BUSINESS_ACCOUNT_ID": "your_business_account_id",
        "WEBHOOK_PORT": "3000"
      }
    }
  }
}

Restart Claude Desktop after saving. You should see the WhatsApp tools available in the tools panel.

Usage with Claude Code

Add to your Claude Code MCP settings (~/.claude/settings.json or project-level .claude/settings.json):

{
  "mcpServers": {
    "whatsapp": {
      "command": "node",
      "args": ["/absolute/path/to/whatsapp-mcp-server/dist/index.js"],
      "env": {
        "WHATSAPP_PHONE_NUMBER_ID": "your_phone_number_id",
        "WHATSAPP_ACCESS_TOKEN": "your_access_token",
        "WHATSAPP_WEBHOOK_VERIFY_TOKEN": "your_verify_token",
        "WHATSAPP_BUSINESS_ACCOUNT_ID": "your_business_account_id",
        "WEBHOOK_PORT": "3000"
      }
    }
  }
}

Or use the CLI to add it:

claude mcp add whatsapp node /absolute/path/to/whatsapp-mcp-server/dist/index.js

Webhook Setup

Webhooks allow you to receive incoming messages and delivery status updates. They are optional — the MCP server works without them for sending messages only.

Local development with ngrok

# 1. Install ngrok: https://ngrok.com/download
# 2. Start your webhook server
WEBHOOK_PORT=3000 npm run dev

# 3. In another terminal, expose it publicly
ngrok http 3000

# 4. Copy the HTTPS URL (e.g. https://abc123.ngrok.io)

Configure in Meta App Dashboard

Go to Meta App Dashboard > Your App > WhatsApp > Configuration
Set Callback URL to: https://your-ngrok-url.ngrok.io/webhook
Set Verify Token to match your WHATSAPP_WEBHOOK_VERIFY_TOKEN
Click Verify and Save
Subscribe to the messages webhook field

Production

For production, deploy this server behind a reverse proxy (nginx, Caddy, etc.) with a valid TLS certificate. Set WEBHOOK_PORT to your internal port and expose it via HTTPS on port 443.

Docker Deployment

Build and run with docker-compose

# Copy and fill in your credentials
cp .env.example .env

# Build and start
docker-compose up -d

# View logs
docker-compose logs -f

# Stop
docker-compose down

Build manually

# Build image
docker build -t whatsapp-mcp-server .

# Run (send-only, no webhook)
docker run --rm -i \
  -e WHATSAPP_PHONE_NUMBER_ID=xxx \
  -e WHATSAPP_ACCESS_TOKEN=xxx \
  whatsapp-mcp-server

# Run with webhook server
docker run --rm -i \
  -p 3000:3000 \
  --env-file .env \
  whatsapp-mcp-server

Note: When using Docker with Claude Desktop/Code, the MCP transport uses stdio. Make sure to pass -i (interactive) so stdin/stdout remain connected. The webhook port is separate from the MCP transport.

Development

# Install dependencies
npm install

# Run with auto-reload
npm run dev

# Type-check only (no build)
npm run typecheck

# Build
npm run build

# Lint
npm run lint

Project structure

src/
├── index.ts              # Entry point — loads env, wires up components
├── server.ts             # MCP server — registers tools, handles requests
├── whatsapp/
│   ├── client.ts         # WhatsApp Cloud API client with retry logic
│   ├── types.ts          # TypeScript types and interfaces
│   └── webhook.ts        # Express webhook server + in-memory store
└── tools/
    ├── messages.ts       # Send/receive message tools
    ├── contacts.ts       # Contact and business profile tools
    ├── media.ts          # Media upload/download/delete tools
    └── templates.ts      # Template message tools

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines on reporting bugs, suggesting features, and submitting pull requests.

License

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

Resources

Need Help?

Related Servers

Latest Blog Posts

Tool Definition Quality Score (TDQS)
By punkpeye on April 3, 2026.
mcp
The Hackers Who Tracked My Sleep Cycle
By punkpeye on March 26, 2026.
security
Open Source Has a Bot Problem
By punkpeye on March 19, 2026.
open source

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/FredShred7/whatsapp-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server