Twilio WhatsApp FastMCP Server

This FastMCP-based server lets you send WhatsApp messages through the Twilio API. It runs as an MCP server and exposes a send_whatsapp tool you can call from an MCP client (for example, an AI model) to deliver messages to WhatsApp recipients.

How to use

You run the server locally and then invoke the send_whatsapp tool from an MCP client. The tool accepts a recipient number (with the whatsapp: prefix) and a message. The server handles authenticating with Twilio and delivering the message to the recipient. Ensure your Twilio account is set up for WhatsApp (Sandbox or a dedicated WhatsApp number) and that the recipient is enrolled if you are using a Sandbox environment.

How to install

Prerequisites: you need Python installed on your system. You may also use a Python virtual environment to isolate dependencies.

# 1) Prepare the project directory
mkdir -p /home/rj/Code/mcp-generated
cd /home/rj/Code/mcp-generated

# 2) Create and activate a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows use `venv\Scripts\activate`

# 3) Install dependencies
pip install twilio python-dotenv pydantic-settings fastmcp

Additional notes and configuration

Configure credentials in a .env file at the project root. Include your Twilio Account SID, Auth Token, and the WhatsApp number you will use to send messages.

Create the following file at /home/rj/Code/mcp-generated/.env with these values, replacing placeholders with your real credentials and number:

TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token_here
TWILIO_WHATSAPP_NUMBER=+14155238886  # Use your Twilio WhatsApp number (Sandbox or purchased)

Run the server and use the send_whatsapp tool

Start the MCP server so the send_whatsapp tool becomes available to remote calls. Use this exact command to run the server from its file path:

python /home/rj/Code/mcp-generated/whatsapp_server.py

Environment and enrollment considerations

If you are using a Twilio Sandbox, you must enroll the recipient numbers in the Sandbox so messages are delivered. A trial account typically uses the Sandbox number whatsapp:+14155238886 as the sending number. Ensure your environment variables reflect the correct numbers and that you follow Twilio’s Sandbox enrollment steps for successful messaging.

Test and example usage

A client can request the send_whatsapp tool with a to_number (including the whatsapp: prefix) and a message. The server processes the request and returns a success or error response after attempting to send the message through Twilio.

Security considerations

Keep your .env file secure and avoid committing credentials to any shared locations. Use a secure method to distribute and reload environment variables if you rotate credentials.

Troubleshooting tips

• If messages fail, verify the Twilio credentials are correct and that the WhatsApp number format is in E.164 with a plus sign. Check that the recipient is enrolled in Sandbox mode if applicable. - Confirm the server is running and listening for MCP calls, and ensure the proper transport (stdio in this setup) is being used by your MCP client.

Available tools

send_whatsapp

Sends a WhatsApp message to a specified recipient using the Twilio API via the MCP server tool endpoint.