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

# Clone the repository
git clone <repository-url>
cd twilio-mcp

# Install dependencies
npm install

# Build the project
npm run build

Configuration

Copy the environment template:

cp .env.example .env

Fill in your Twilio credentials in .env:

# Get these from https://console.twilio.com
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token_here
TWILIO_PHONE_NUMBER=+1234567890

# Webhook configuration
WEBHOOK_PORT=3000
WEBHOOK_BASE_URL=https://your-domain.com

# Database path
DATABASE_PATH=./data/twilio.db

Setting Up Webhooks

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

Development (Using ngrok)

Install ngrok: https://ngrok.com/download
Start the webhook server:

npm run dev

In another terminal, start ngrok:

ngrok http 3000

Copy the HTTPS URL from ngrok (e.g., https://abc123.ngrok.io)
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:

{
  "mcpServers": {
    "twilio": {
      "command": "node",
      "args": ["/path/to/twilio-mcp/dist/index.js"],
      "env": {
        "TWILIO_ACCOUNT_SID": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "TWILIO_AUTH_TOKEN": "your_auth_token",
        "TWILIO_PHONE_NUMBER": "+1234567890",
        "WEBHOOK_PORT": "3000",
        "WEBHOOK_BASE_URL": "https://your-webhook-url.com",
        "DATABASE_PATH": "./data/twilio.db"
      }
    }
  }
}

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:

{
  "to": "+1234567890",
  "message": "Hello from Twilio MCP!"
}

Response:

{
  "messageSid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "status": "queued",
  "to": "+1234567890",
  "from": "+1987654321",
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-01-15T10:30:00.000Z"
}

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:

{
  "from": "+1234567890",
  "limit": 10
}

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:

{
  "participants": ["+1234567890", "+1987654321"],
  "metadata": {
    "campaign": "support",
    "priority": "high"
  }
}

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:

{
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "includeContext": true
}

get_message_status

Check the delivery status of a sent message.

Parameters:

messageSid (required): Twilio message SID

Example:

{
  "messageSid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Response:

{
  "messageSid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "status": "delivered",
  "timestamp": "2025-01-15T10:31:00.000Z",
  "to": "+1234567890",
  "from": "+1987654321"
}

Conversation Threading

The server automatically creates and manages conversation threads:

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
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
Participant Matching: Conversations are identified by normalized participant pairs:
- [+1234567890, +1987654321] matches the same conversation regardless of direction

Architecture

twilio-mcp/
├── src/
│   ├── index.ts                 # MCP server entry point
│   ├── server.ts                # MCP server with tool registry
│   ├── webhook-server.ts        # Express server for webhooks
│   ├── config/
│   │   └── env.ts               # Environment configuration
│   ├── services/
│   │   └── twilio-client.ts     # Twilio SDK wrapper
│   ├── storage/
│   │   ├── conversation-store.ts # Conversation persistence
│   │   └── message-store.ts      # Message persistence
│   ├── tools/
│   │   ├── send-sms.ts
│   │   ├── get-inbound-messages.ts
│   │   ├── create-conversation.ts
│   │   ├── get-conversation-thread.ts
│   │   └── get-message-status.ts
│   └── types/
│       └── models.ts            # TypeScript type definitions
└── data/                        # SQLite database storage

Development

# Run in development mode
npm run dev

# Build TypeScript
npm run build

# Run tests
npm test

# Type check
npm run lint

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

Variable	Required	Default	Description
`TWILIO_ACCOUNT_SID`	Yes	-	Twilio Account SID (starts with AC)
`TWILIO_AUTH_TOKEN`	Yes	-	Twilio Auth Token
`TWILIO_PHONE_NUMBER`	Yes	-	Your Twilio phone number (E.164 format)
`WEBHOOK_PORT`	No	3000	Port for webhook server
`WEBHOOK_BASE_URL`	Yes	-	Public HTTPS URL for webhooks
`DATABASE_PATH`	No	./data/twilio.db	SQLite database file path
`LOG_LEVEL`	No	info	Logging level (debug, info, warn, error)
`AUTO_CREATE_CONVERSATIONS`	No	true	Auto-create conversations for new threads
`ENABLE_AI_CONTEXT`	No	true	Enable AI context generation
`ENABLE_MMS`	No	true	Enable MMS support