PyWA

Exposes full WhatsApp Business API capabilities via MCP with messaging, templating, interactive UI, and status tools.

python

1

GitHub Stars

python

Language

5 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "jem-hr-pywa-mcp-server": {
      "command": "uv",
      "args": [
        "run",
        "fastmcp",
        "dev",
        "--ui-port",
        "6275",
        "server.py"
      ],
      "env": {
        "WHATSAPP_TOKEN": "your_token",
        "WHATSAPP_PHONE_ID": "your_phone_id"
      }
    }
  }
}

You run a PyWA MCP Server to expose full WhatsApp Business API functionality via a modular MCP interface. This lets you send messages, templates, media, interactive elements, and status indicators to WhatsApp users through a programmable, observable API that integrates with your existing tools and workflows.

How to use

You connect an MCP client to the PyWA MCP Server to perform messaging and management actions on WhatsApp. With the available tools, you can send text, media, locations, contacts, and reactions; create interactive messages with buttons or lists; send pre-approved templates; and indicate typing or read status. Use the client to call the corresponding tool endpoints, supply the required recipient and payload fields, and receive structured success or error responses. Test flows incrementally—start with simple text messages, then add media, interactivity, and templates to verify end-to-end behavior.

For development and testing, you can access a Web UI that visualizes all tools, real-time API calls, and responses. Use the UI to validate messages, buttons, lists, and templates before integrating into your production workflows.

How to install

Prerequisites you need before installing: Python runtime and the MCP tooling used by PyWA MCP Server.

# Install dependencies (installation step included in typical setup)
uv sync

Configure your WhatsApp credentials in a local environment file. Create or copy the example and fill in your credentials from the Meta Developer Console.

cp .env.example .env
# Edit .env with your WHATSAPP_PHONE_ID and WHATSAPP_TOKEN

Run the server in production mode to start handling requests.

uv run python server.py

For development and testing with a Web UI, start the development server with the UI enabled on port 6275.

uv run fastmcp dev --ui-port 6275 server.py

Configuration and environment

Set these environment variables to authorize and address your WhatsApp Cloud API account.

WHATSAPP_PHONE_ID=your_phone_id
WHATSAPP_TOKEN=your_token

Development & testing tips

Web UI is recommended for development. It lets you view all tools, test messaging, buttons, lists, and templates, see real-time API calls, and debug with comprehensive error messages.

If you want to test against real WhatsApp, obtain credentials from Meta Developer Console, add test numbers there, and use the Web UI to send messages to those numbers. Verify delivery by checking the recipient inbox.

Claude Desktop integration (example workflows)

You can integrate with Claude Desktop by configuring an MCP server entry that runs locally and exports the PyWA MCP Server via the MCP runtime.

Quick setup (one command) and reusable configuration examples are provided to enable Claude Desktop to launch the server and connect to MCP.

Available tools

send_message

Send a text message to a WhatsApp user, with optional header/footer and delivery options.

send_image

Send an image with an optional caption to a WhatsApp user.

send_video

Send a video with a caption to a recipient.

send_document

Send a document/file with a custom name to a recipient.

send_audio

Send an audio message to a recipient.

send_sticker

Send a WebP sticker to a recipient.

send_location

Send GPS coordinates to share a location with the user.

request_location

Request the user’s location.

send_contact

Send a contact card to a recipient.

send_reaction

Add an emoji reaction to a message.

remove_reaction

Remove a previously added reaction from a message.

upload_media

Upload media to the WhatsApp server for later use.

send_message_with_buttons

Send an interactive message with up to three reply buttons.

send_message_with_list

Send an interactive list message with sections for user selection.

send_template

Send a pre-approved template message to a user.

get_templates

Retrieve available pre-approved templates.

mark_message_as_read

Mark a received message as read.

indicate_typing

Show a typing indicator for a message being prepared.