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:

result = await send_sms(
    to="+1234567890",
    from_="+1987654321",
    body="Hello from Twilio MCP!",
    media_url="https://example.com/image.jpg"
)

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:

result = await send_whatsapp(
    to="whatsapp:+1234567890",
    from_="whatsapp:+1987654321",
    body="Hello from WhatsApp!",
    media_url="https://example.com/image.jpg"
)

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:

messages = await list_messages(from_="+1987654321", page_size=20)

get_message

Get details of a specific message.

Parameters:

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

Example:

message = await get_message(message_sid="SM1234567890abcdef")

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:

call = await make_call(
    to="+1234567890",
    from_="+1987654321",
    url="https://example.com/twiml",
    status_callback="https://example.com/status"
)

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:

calls = await list_calls(status="completed", page_size=10)

get_call

Get details of a specific call.

Parameters:

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

Example:

call = await get_call(call_sid="CA1234567890abcdef")

Account & Phone Number Tools

get_account_balance

Get your current Twilio account balance.

Example:

balance = await get_account_balance()
# Returns: {"balance": "100.00", "currency": "USD"}

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:

numbers = await list_phone_numbers(page_size=10)

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:

info = await lookup_phone_number(
    phone_number="+1234567890",
    type_="carrier"
)

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:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Say>Hello! This is a call from Twilio.</Say>
</Response>

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