Twilio MCP Server

MCP server for interacting with the Twilio communication API. Send SMS and WhatsApp messages, make phone calls, and manage your Twilio account.

Features

• SMS Messaging: Send and manage SMS/MMS messages

• WhatsApp Messaging: Send WhatsApp messages via Twilio

• Voice Calls: Initiate and manage phone calls

• Phone Number Management: List and lookup phone numbers

• Account Management: Check balance and account status

Setup

Prerequisites

• Twilio account (sign up at twilio.com)

• Twilio phone number (for sending SMS/calls)

• Account credentials from Twilio Console

Environment Variables

• TWILIO_ACCOUNT_SID (required): Your Twilio Account SID

• TWILIO_AUTH_TOKEN (required): Your Twilio Auth Token

How to get credentials:

1. Go to console.twilio.com

2. Find your Account SID and Auth Token in the dashboard

3. Keep these secure - they provide full access to your Twilio account

Available Tools

Messaging Tools

send_sms

Send an SMS message.

Parameters:

• to (string, required): Recipient phone number in E.164 format (e.g., +1234567890)

• from_ (string, required): Your Twilio phone number in E.164 format

• body (string, required): Message content (up to 1600 characters)

• media_url (string, optional): URL of media to send (converts to MMS)

Example:

send_whatsapp

Send a WhatsApp message via Twilio.

Parameters:

• to (string, required): Recipient WhatsApp number (e.g., whatsapp:+1234567890)

• from_ (string, required): Your Twilio WhatsApp number (e.g., whatsapp:+1987654321)

• body (string, required): Message content

• media_url (string, optional): URL of media to send

Example:

list_messages

List sent and received messages with optional filters.

Parameters:

• to (string, optional): Filter by recipient phone number

• from_ (string, optional): Filter by sender phone number

• date_sent (string, optional): Filter by date in YYYY-MM-DD format

• page_size (int, optional): Number of results (default: 50, max: 1000)

Example:

get_message

Get details of a specific message.

Parameters:

• message_sid (string, required): The Twilio message SID (e.g., SMxxxxx)

Example:

Voice Call Tools

make_call

Initiate an outbound phone call.

Parameters:

• to (string, required): Recipient phone number in E.164 format

• from_ (string, required): Your Twilio phone number in E.164 format

• url (string, required): URL that returns TwiML instructions for the call

• method (string, optional): HTTP method (GET or POST, default: POST)

• status_callback (string, optional): URL for call status updates

Example:

list_calls

List call logs with optional filters.

Parameters:

• to (string, optional): Filter by recipient phone number

• from_ (string, optional): Filter by caller phone number

• status (string, optional): Filter by status (queued, ringing, in-progress, completed, etc.)

• page_size (int, optional): Number of results (default: 50, max: 1000)

Example:

get_call

Get details of a specific call.

Parameters:

• call_sid (string, required): The Twilio call SID (e.g., CAxxxxx)

Example:

Account & Phone Number Tools

get_account_balance

Get your current Twilio account balance.

Example:

list_phone_numbers

List phone numbers owned by your Twilio account.

Parameters:

• page_size (int, optional): Number of results (default: 50, max: 1000)

• phone_number (string, optional): Filter by specific phone number

• friendly_name (string, optional): Filter by friendly name

Example:

lookup_phone_number

Validate and get information about a phone number.

Parameters:

• phone_number (string, required): Phone number to lookup in E.164 format

• country_code (string, optional): ISO country code if using national format (e.g., 'US')

• type_ (string, optional): Additional data ('carrier' or 'caller-name')

Example:

Phone Number Format

All phone numbers must be in E.164 format:

• Start with + followed by country code

• Example US number: +14155552671

• Example UK number: +442071838750

Rate Limits and Pricing

Rate Limits

• SMS: 100 messages per second per account (contact Twilio to increase)

• Voice: 100 concurrent calls per account (contact Twilio to increase)

• API Requests: 10,000 requests per second

Pricing (as of 2024, subject to change)

• SMS (US): $0.0079 per message

• WhatsApp: $0.005 per conversation (first 1,000 free monthly)

• Voice (US): $0.0140 per minute

• Phone Number: $1.15 per month

• Lookup API: $0.005 per request (carrier info extra)

Visit Twilio Pricing for current rates.

Security Best Practices

1. Never commit credentials: Keep TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN in environment variables

2. Use API keys: Consider using Twilio API Keys for additional security

3. Enable IP filtering: Restrict API access to specific IP addresses in Twilio Console

4. Monitor usage: Set up usage alerts in Twilio Console to detect unusual activity

5. Rotate credentials: Periodically rotate your Auth Token

6. Use test credentials: Use test credentials for development (prefix with AC for test accounts)

TwiML Resources

For making calls with make_call, you need a URL that returns TwiML (Twilio Markup Language):

Simple TwiML example:

Learn more about TwiML at twilio.com/docs/voice/twiml

API Documentation

For detailed information about the Twilio API:

• Twilio API Documentation

• Messaging API

• Voice API

• WhatsApp API

• Lookup API

Error Handling

Common errors and solutions:

• 21211: Invalid phone number - Ensure E.164 format

• 21608: Unverified number - Verify trial account numbers in Console

• 21610: Message blocked - Check compliance and opt-in requirements

• 20003: Authentication error - Verify credentials are correct

• 20429: Rate limit exceeded - Implement exponential backoff

Support

• Twilio Support

• Twilio Community

• Twilio Console