Twilio MCP Server

A Model Context Protocol (MCP) server for Twilio that enables AI-powered SMS messaging with intelligent conversation management.

Features

• Send SMS - Send text messages via Twilio with automatic conversation threading

• Receive SMS - Process inbound messages via webhooks with automatic storage

• Conversation Management - Track and manage multi-turn SMS conversations

• Message Status - Check delivery status of sent messages

• Thread Association - Automatically link messages to conversation threads

• MMS Support - Send and receive multimedia messages (optional)

Installation

Configuration

1. Copy the environment template:

2. Fill in your Twilio credentials in .env:

Setting Up Webhooks

For the server to receive inbound SMS, you need to configure Twilio webhooks:

Development (Using ngrok)

1. Install ngrok: https://ngrok.com/download

2. Start the webhook server:

3. In another terminal, start ngrok:

4. Copy the HTTPS URL from ngrok (e.g., https://abc123.ngrok.io)

5. Configure Twilio webhook:

   • Go to https://console.twilio.com/us1/develop/phone-numbers/manage/incoming

   • Select your phone number

   • Under "Messaging Configuration":

     • Webhook URL: https://abc123.ngrok.io/webhooks/twilio/sms

     • HTTP Method: POST

   • Under "Status Callback URL":

     • URL: https://abc123.ngrok.io/webhooks/twilio/status

   • Save

Production

Deploy the webhook server to a production environment with HTTPS and configure the Twilio webhook URLs accordingly.

Usage with Claude Code

Add this server to your Claude Code MCP configuration:

MCP Tools

send_sms

Send an SMS message via Twilio.

Parameters:

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

• message (required): SMS content (1-1600 characters)

• from (optional): Sender phone number (uses default if not provided)

• conversationId (optional): UUID of existing conversation

Example:

Response:

get_inbound_messages

Query received SMS/MMS messages from storage.

Parameters:

• from (optional): Filter by sender phone number

• to (optional): Filter by recipient phone number

• conversationId (optional): Filter by conversation UUID

• since (optional): ISO 8601 timestamp to filter messages after this date

• limit (optional): Maximum messages to return (default: 50)

Example:

create_conversation

Initialize a new conversation thread.

Parameters:

• participants (required): Array of phone numbers in E.164 format (min 2)

• metadata (optional): Custom metadata object

Example:

get_conversation_thread

Retrieve full conversation history with all messages.

Parameters:

• conversationId (required): UUID of the conversation

• includeContext (optional): Include AI context summary (default: false)

Example:

get_message_status

Check the delivery status of a sent message.

Parameters:

• messageSid (required): Twilio message SID

Example:

Response:

Conversation Threading

The server automatically creates and manages conversation threads:

1. Outbound Messages: When sending an SMS:

   • If conversationId is provided, the message is linked to that conversation

   • If not provided, the server finds an existing conversation by participant pair

   • If no conversation exists and AUTO_CREATE_CONVERSATIONS=true, a new one is created

2. Inbound Messages: When receiving an SMS via webhook:

   • The server matches by participant pair (from/to numbers)

   • If no conversation exists and AUTO_CREATE_CONVERSATIONS=true, a new one is created

   • Messages are automatically stored and linked to the conversation

3. Participant Matching: Conversations are identified by normalized participant pairs:

   • [+1234567890, +1987654321] matches the same conversation regardless of direction

Architecture

Development

Testing

The project includes a comprehensive test suite using Jest with TypeScript support.

Test Structure

What's Tested

• Schema Validation: All MCP tool input schemas are tested for valid/invalid inputs

• Storage Operations: SQLite conversation and message stores (CRUD operations)

• Webhook Handlers: Inbound SMS and status callback endpoints with signature validation

• Environment Config: All environment variable validation rules

• Twilio Client: Client instantiation and method signatures

Running Tests

Test Environment

Tests use an in-memory SQLite database and mock environment variables configured in tests/setup.ts.

Security

• No Hardcoded Secrets: All credentials are stored in environment variables

• Webhook Validation: All Twilio webhooks are validated using signature verification

• Input Validation: All tool inputs are validated using Zod schemas

• HTTPS Required: Webhook endpoints must use HTTPS in production

Database

The server uses SQLite for storing conversations and messages:

• Conversations: Thread metadata, participants, timestamps

• Messages: SMS/MMS content, delivery status, media URLs

Database file location: ./data/twilio.db (configurable via DATABASE_PATH)

Environment Variables

License

MIT

Support

For issues and questions:

• Twilio Documentation: https://www.twilio.com/docs

• MCP Documentation: https://modelcontextprotocol.io