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

Option 2: From PyPI (when published)

⚙️ Configuration

Environment Setup

Create a .env file in your project root:

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:

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

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

🛠️ 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_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:

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:

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

🔧 Development

Setup Development Environment

Code Formatting

Type Checking

Testing

📝 Usage Examples

Basic Text Message

Image with Caption

Interactive List

Template with 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.