home / mcp / whatsapp mcp server

WhatsApp MCP Server

Provides an MCP server for WhatsApp Business API to send messages, manage templates, and handle interactive communications.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "ampcome-mcps-whatsapp-mcp": {
      "command": "python",
      "args": [
        "-m",
        "whatsapp_mcp.server"
      ],
      "env": {
        "NANGO_BASE_URL": "https://api.nango.dev",
        "NANGO_SECRET_KEY": "your_nango_secret_key",
        "NANGO_CONNECTION_ID": "your_nango_connection_id",
        "NANGO_INTEGRATION_ID": "whatsapp-business",
        "WHATSAPP_PHONE_NUMBER_ID": "your_whatsapp_phone_number_id",
        "WHATSAPP_BUSINESS_ACCOUNT_ID": "your_whatsapp_business_account_id"
      }
    }
  }
}

You are deploying a dedicated MCP server for WhatsApp Business API integration. This server enables you to send text, media, interactive, and template messages, manage templates, and handle end‑to‑end WhatsApp communications through a clean, modular Python-based implementation. It is designed to scale for enterprise use with robust error handling and secure configuration via environment variables.

How to use

Start by running the MCP server locally and then connect your MCP client. The server communicates via the MCP stdio transport, so it reads from stdin and writes to stdout. You can run the server module directly and then interact with it through your MCP client to perform messaging, templates, and interactive flows.

Typical usage patterns include sending plain text messages, sending media (images, videos, documents, audio), dispatching template messages with dynamic parameters, and using interactive messages such as lists or button menus. You can also create and check template statuses and list available templates for your WhatsApp Business account.

To start the server from your environment, use one of the following commands depending on how you prefer to run it: python -m whatsapp_mcp.server or python main.py or, if you installed it as a package, whatsapp-mcp from your shell. The server is intended for MCP clients like Claude Desktop and should be run in stdio mode rather than in an interactive shell.

How to install

Prerequisites: ensure you have Python 3.x and pip installed on your system.

Option 1 — Direct installation from source

Clone the repository and install in editable mode so you can develop against the codebase.

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

Option 2 — Install from PyPI (when published)

Install the package directly from PyPI.

pip install whatsapp-mcp

Configure and run the server

Prepare the environment variables needed for Nango integration and WhatsApp credentials. You will typically set NANGO_CONNECTION_ID, NANGO_INTEGRATION_ID, NANGO_BASE_URL, NANGO_SECRET_KEY, WHATSAPP_PHONE_NUMBER_ID, and WHATSAPP_BUSINESS_ACCOUNT_ID. These variables can be set in a .env file at your project root or exported in your shell.

Start the MCP server using Python as a module. This runs the MCP server in stdio mode so MCP clients can communicate with it.

python -m whatsapp_mcp.server

Available tools

send_text_message

Send text messages or template messages to WhatsApp users using either environment defaults or explicit overrides for phone_number_id and language.

send_image_message

Send an image to a recipient with an optional caption and a specified phone_number_id.

send_video_message

Send a video to a recipient with an optional caption and a specified phone_number_id.

send_document_message

Send a document to a recipient with an optional caption and filename, using a specified phone_number_id.

send_audio_message

Send an audio file or voice message to a recipient with a specified phone_number_id.

send_list_message

Send an interactive list message with sections and options to a recipient, including header/body/footer and button text.

send_button_message

Send an interactive message with up to three buttons to a recipient, with optional header and footer text.

send_template_message

Send an approved template with dynamic parameters to a recipient, using a language code and optional parameters.

check_template_status

Check the approval status of a specific template for a given business account.

list_templates

List all templates for your WhatsApp Business account, with optional status filtering.

create_template

Create a new WhatsApp message template with a specified language and category and associated components.