WhatsApp MCP Server

A comprehensive Model Context Protocol (MCP) server for WhatsApp Business API integration. This server provides powerful tools for sending various types of messages, managing templates, and handling interactive communications through WhatsApp Business API.

🚀 Features

Message Types

• Text Messages - Send plain text and template messages
• Media Messages - Send images, videos, documents, and audio files
• Interactive Messages - Send lists and button menus
• Template Messages - Send approved templates with dynamic parameters

Template Management

• Create Templates - Design new message templates
• Check Status - Monitor template approval status
• List Templates - View all available templates

Enterprise Ready

• Clean Architecture - Modular, maintainable codebase
• Error Handling - Robust error handling and logging
• Type Safety - Full type hints for better development experience
• Environment Based - Secure credential management

📦 Installation

Option 1: Direct Installation

git clone <repository-url>
cd whatsapp-mcp
pip install -e .

Option 2: From PyPI (when published)

pip install whatsapp-mcp

⚙️ Configuration

Environment Setup

Create a .env file in your project root:

# Nango Configuration for WhatsApp Business API
NANGO_CONNECTION_ID=your_nango_connection_id
NANGO_INTEGRATION_ID=whatsapp-business
NANGO_BASE_URL=https://api.nango.dev
NANGO_SECRET_KEY=your_nango_secret_key

# WhatsApp Business Configuration (Optional - can be set per call)
WHATSAPP_PHONE_NUMBER_ID=your_whatsapp_phone_number_id
WHATSAPP_BUSINESS_ACCOUNT_ID=your_whatsapp_business_account_id

Configuration Benefits

Environment Variables: Set your phone number ID and business account ID once in environment variables, then use them across all function calls without needing to specify them each time.

Flexibility: You can still override the environment variables by passing explicit values to individual function calls when needed.

Simplicity: For most use cases, you'll only need to set the environment variables once and then use simpler function calls:

# Simple - uses environment variables
send_text_message(to="+1234567890", message="Hello!")

# Explicit - overrides environment variables  
send_text_message(to="+1234567890", message="Hello!", phone_number_id="different_id")

Getting Nango Credentials

1. Set up a Nango account
2. Create a WhatsApp Business integration in Nango
3. Set up your WhatsApp Business API connection
4. Get your Nango connection ID and secret key

Getting WhatsApp Credentials

1. Set up a WhatsApp Business Account
2. Create a Meta Developer App
3. Add WhatsApp Business API to your app
4. Configure the integration in Nango with your WhatsApp credentials

Running the Server

# Run using the installed command
whatsapp-mcp

# Or run directly from source
python main.py

# Or as a module
python -m whatsapp_mcp.server

# Show help
python main.py --help

Note: This server uses the MCP stdio transport protocol and is designed to be run by MCP clients like Claude Desktop. It communicates via stdin/stdout and should not be run directly in interactive mode.

🤖 Claude Desktop Integration

Add this configuration to your Claude Desktop config file:

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Windows

%APPDATA%/Claude/claude_desktop_config.json

Linux

~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "whatsapp": {
      "command": "uvx",
      "args": ["git+https://github.com/ampcome-mcps/whatsapp-mcp.git"],
      "env": {
        "NANGO_CONNECTION_ID": "your_nango_connection_id",
        "NANGO_INTEGRATION_ID": "whatsapp-business",
        "NANGO_BASE_URL": "https://api.nango.dev",
        "NANGO_SECRET_KEY": "your_nango_secret_key",
        "WHATSAPP_PHONE_NUMBER_ID": "your_whatsapp_phone_number_id",
        "WHATSAPP_BUSINESS_ACCOUNT_ID": "your_whatsapp_business_account_id"
      }
    }
  }
}

🛠️ Available Tools

Message Tools

send_text_message

Send text messages or templates to WhatsApp users.

Parameters:

• to (str): Recipient's phone number with country code
• message (str, optional): Text message content
• template_name (str, optional): Template name to use
• language_code (str): Language code for templates (default: "en_US")
• phone_number_id (str, optional): Your WhatsApp Business phone number ID (uses env var if not provided)

Example Usage:

# Send text message (using environment variable for phone_number_id)
send_text_message(
    to="+1234567890", 
    message="Hello! How can I help you today?"
)

# Send text message with explicit phone_number_id
send_text_message(
    to="+1234567890", 
    message="Hello! How can I help you today?",
    phone_number_id="1234567890"
)

# Send template message
send_text_message(
    to="+1234567890",
    template_name="welcome_message",
    language_code="en_US"
)

send_image_message

Send images with optional captions.

Parameters:

• to (str): Recipient's phone number
• image_url (str): Public URL of the image
• caption (str, optional): Image caption
• phone_number_id (str, optional): Your WhatsApp Business phone number ID (uses env var if not provided)

send_video_message

Send videos with optional captions.

Parameters:

• to (str): Recipient's phone number
• video_url (str): Public URL of the video
• caption (str, optional): Video caption
• phone_number_id (str, optional): Your WhatsApp Business phone number ID (uses env var if not provided)

send_document_message

Send documents like PDFs, Word files, etc.

Parameters:

• to (str): Recipient's phone number
• document_url (str): Public URL of the document
• caption (str, optional): Document caption
• filename (str, optional): Filename for the document
• phone_number_id (str, optional): Your WhatsApp Business phone number ID (uses env var if not provided)

send_audio_message

Send audio files and voice messages.

Parameters:

• to (str): Recipient's phone number
• audio_url (str): Public URL of the audio file
• phone_number_id (str, optional): Your WhatsApp Business phone number ID (uses env var if not provided)

Interactive Tools

send_list_message

Send interactive list messages with selectable options.

Parameters:

• to (str): Recipient's phone number
• sections (list): List of sections with options
• header_text (str): Header text (default: "Available Options")
• body_text (str): Body text
• footer_text (str): Footer text
• button_text (str): Button text (default: "Options")
• phone_number_id (str, optional): Your WhatsApp Business phone number ID (uses env var if not provided)

Example Usage:

sections = [
    {
        "title": "Main Menu",
        "rows": [
            {
                "id": "option_1",
                "title": "Product Info",
                "description": "Get information about our products"
            },
            {
                "id": "option_2",
                "title": "Support",
                "description": "Contact customer support"
            }
        ]
    }
]

send_list_message(
    to="+1234567890",
    sections=sections,
    body_text="How can we help you today?"
)

send_button_message

Send interactive messages with up to 3 buttons.

Parameters:

• to (str): Recipient's phone number
• body_text (str): Main message text
• buttons (list): List of buttons (max 3)
• header_text (str, optional): Header text
• footer_text (str, optional): Footer text
• phone_number_id (str, optional): Your WhatsApp Business phone number ID (uses env var if not provided)

Template Tools

send_template_message

Send approved template messages with dynamic parameters.

Parameters:

• to (str): Recipient's phone number
• template_name (str): Name of approved template
• parameters (list, optional): List of parameters for template variables
• language (str): Template language code (default: "en")
• phone_number_id (str, optional): Your WhatsApp Business phone number ID (uses env var if not provided)

Example Usage:

parameters = [
    {"type": "text", "text": "John Smith"},
    {"type": "text", "text": "December 25, 2024"}
]

send_template_message(
    to="+1234567890",
    template_name="appointment_reminder",
    parameters=parameters,
    language="en"
)

check_template_status

Check the approval status of a template.

Parameters:

• template_name (str): Name of the template to check
• business_account_id (str, optional): WhatsApp Business Account ID (uses env var if not provided)

list_templates

List all templates for your business account.

Parameters:

• status_filter (str, optional): Filter by status (APPROVED, PENDING, REJECTED)
• business_account_id (str, optional): WhatsApp Business Account ID (uses env var if not provided)

create_template

Create a new message template.

Parameters:

• template_name (str): Name for the new template
• language (str): Language code
• category (str): Template category (MARKETING, UTILITY, AUTHENTICATION)
• components (list): List of template components
• business_account_id (str, optional): WhatsApp Business Account ID (uses env var if not provided)

📁 Project Structure

whatsapp-mcp/
├── src/
│   └── whatsapp_mcp/
│       ├── __init__.py
│       ├── server.py          # Main server entry point
│       ├── tools/            # MCP tools
│       │   ├── __init__.py
│       │   ├── messages.py   # Message sending tools
│       │   ├── interactive.py # Interactive message tools
│       │   └── templates.py  # Template management tools
│       └── utils/            # Utilities
│           ├── __init__.py   # Core utilities
│           └── client.py     # WhatsApp API client
├── .env.example              # Environment template
├── pyproject.toml           # Project configuration
└── README.md               # This file

🔧 Development

Setup Development Environment

git clone <repository-url>
cd whatsapp-mcp
pip install -e ".[dev]"

Code Formatting

black src/
isort src/

Type Checking

mypy src/

Testing

pytest

📝 Usage Examples

Basic Text Message

# Send a simple text message (using environment variables)
result = send_text_message(
    to="+1234567890",
    message="Hello! Welcome to our service."
)

Image with Caption

# Send an image with caption
result = send_image_message(
    to="+1234567890", 
    image_url="https://example.com/image.jpg",
    caption="Check out our new product!"
)

Interactive List

# Send an interactive list
sections = [
    {
        "title": "Services",
        "rows": [
            {
                "id": "service_1",
                "title": "Web Development", 
                "description": "Custom website development"
            },
            {
                "id": "service_2",
                "title": "Mobile Apps",
                "description": "iOS and Android app development"
            }
        ]
    }
]

result = send_list_message(
    to="+1234567890",
    sections=sections,
    body_text="What service are you interested in?"
)

Template with Parameters

# Send template with dynamic content
parameters = [
    {"type": "text", "text": "Alice Johnson"},
    {"type": "text", "text": "Premium"},
    {"type": "text", "text": "January 15, 2025"}
]

result = send_template_message(
    to="+1234567890",
    template_name="subscription_confirmation",
    parameters=parameters
)

🔒 Security

• Environment Variables: Store sensitive data like access tokens in environment variables
• Input Validation: All inputs are validated before API calls
• Error Handling: Secure error messages that don't expose sensitive information
• Rate Limiting: Respect WhatsApp API rate limits

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Documentation: Check this README and inline code documentation
• Issues: Report bugs and request features via GitHub Issues
• WhatsApp API: Refer to WhatsApp Business API Documentation

🔄 Changelog

v0.1.0

• Initial release
• Basic message sending capabilities
• Template management
• Interactive messages
• Claude Desktop integration
• Clean modular architecture

---

Note: This MCP server requires a WhatsApp Business API account and valid access tokens. Make sure to comply with WhatsApp's terms of service and messaging policies.