Twilio MCP Server

How to use

You connect to the Twilio MCP Server from your MCP client by configuring a server entry that points to the local or remote server executable. Use the standard MCP tools to create conversations, send SMS, query inbound messages, and check delivery status. The server automatically links messages to conversations based on participant pairs and can create new conversations when needed if auto-create is enabled.

How to install

# Prerequisites
- Node.js (LTS version) installed on your system
- npm available in your environment

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

# Install dependencies
npm install

# Build the project
npm run build

Configuration and runtime environment

Configure the server with your Twilio credentials and webhook settings. The example below shows the environment variables you will use when running the server in an MCP client. Copy the template, fill in your values, and pass them to the server process.

# Environment configuration example
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
```

# Example start commands (standalone runtime)
# Local start (dev/prod can differ):
npm run dev  # or the appropriate startup command for your environment

Development and testing

During development you can run the server in development mode and expose webhooks with a tunnel. Then you configure your Twilio webhook URLs to point to the tunnel endpoint. The project includes a Jest-based test suite to validate schemas, storage, webhook handling, environment configuration, and the Twilio client integration.

Tools and endpoints

The MCP tools exposed by the Twilio MCP Server include functions for sending SMS, querying inbound messages, creating conversations, fetching conversation threads, and checking message delivery status. These tools enable you to build end-to-end SMS workflows with automatic conversation threading.

Security considerations

No credentials are embedded in code. All secrets are supplied via environment variables. Webhook endpoints are validated to ensure requests originate from Twilio, and input validation is performed to prevent invalid data. Ensure your webhook base URL uses HTTPS in production.

Environment variables

The following environment variables are used by the Twilio MCP Server. Provide them in your runtime environment or via your MCP client configuration.

Database and storage

The server stores conversations and messages in SQLite. Conversations track participants and metadata, while messages store content, delivery status, and media references. You can configure the path to the database with DATABASE_PATH.

send_sms

Send an SMS message via Twilio, optionally associating it with a conversation and returning details such as message SID and status.

get_inbound_messages

Query received messages stored in the database with optional filters like sender, recipient, conversation, and date range.

create_conversation

Initialize a new conversation thread with a list of participant phone numbers and optional metadata.

get_conversation_thread

Retrieve full conversation history for a given conversation, with optional AI context inclusion.

get_message_status

Check the delivery status of a previously sent Twilio message by its SID.