Twilio Messaging MCP Server

🚀 Twilio Messaging MCP Server

This is an MCP server for sending SMS messages via the Twilio API. It offers tools, resources, and prompts for interacting with the Twilio Messaging API.

🚀 Quick Start

This server simplifies the process of sending SMS messages through Twilio. With necessary configurations, you can quickly start using it to send messages and handle callbacks.

✨ Features

• Send SMS messages via Twilio.
• Receive and enhance Twilio's status callbacks (using @deshartman/mcp-status-callback).
• Integrate Claude AI through the Model Context Protocol (MCP).
• Can be executed via npx for easy use without installation.

📦 Installation

You can install the package using npm:

npm install @deshartman/twilio-messaging-mcp-server

Or run it directly via npx:

npx @deshartman/twilio-messaging-mcp-server <accountSid> <apiKey> <apiSecret> <number>

Using npx

Run the package directly with npx without installation:

# Run with required parameters
npx @deshartman/twilio-messaging-mcp-server <accountSid> <apiKey> <apiSecret> <number>

# Use ngrok with environment variables
env NGROK_AUTH_TOKEN=your_token NGROK_CUSTOM_DOMAIN=your_domain.ngrok.dev npx @deshartman/twilio-messaging-mcp-server <accountSid> <apiKey> <apiSecret> <number>

This is possible because the package's package.json contains a "bin" field, making it executable via npx.

💻 Usage Examples

Running the Server

You can use the provided script and run it through a .env file:

# Create a .env file containing your credentials
# Check .env.example for the required format

# Start the server (no parameters needed)
./run-server.sh

The .env file should contain the following:

ACCOUNT_SID=YOUR_ACCOUNT_SID
API_KEY=YOUR_API_KEY
API_SECRET=YOUR_API_SECRET
TWILIO_NUMBER=YOUR_TWILIO_PHONE_NUMBER
NGROK_AUTH_TOKEN=YOUR_NGROK_AUTH_TOKEN
NGROK_CUSTOM_DOMAIN=your-domain.ngrok.dev

This approach enhances security by avoiding exposing credentials in the command history and simplifies the execution process.

Using Node.js Directly

env NGROK_AUTH_TOKEN=your_ngrok_auth_token NGROK_CUSTOM_DOMAIN=your_domain.ngrok.dev node build/index.js <accountSid> <apiKey> <apiSecret> <number>

Prerequisites

• Node.js >= 18.0.0
• A Twilio account with the following information:
  • Account SID
  • API Key and Secret
  • Twilio phone number
• An ngrok account with the following information:
  • Authentication token
  • Custom domain (optional)

Environment Variables

• NGROK_AUTH_TOKEN: Your ngrok authentication token (required for handling callbacks).
• NGROK_CUSTOM_DOMAIN: Your custom ngrok domain (optional).

📚 Documentation

MCP Integration

This server provides the following MCP features:

Tools

• send-sms: Send SMS messages via Twilio with server readiness verification.

Resources

• twilio://statuscallback: Get the last raw status callback data from Twilio and perform enhanced error handling.

Prompts

• SendSMS: A prompt for sending SMS using the Twilio Messaging MCP Server.

Troubleshooting

ngrok Tunnel Issues

If you encounter the following error:

failed to start tunnel: The endpoint 'https://your-domain.ngrok.dev' is already online.

You can try one of the following methods:

1. Stop the existing endpoint first.
2. Use a different domain.
3. Enable load balancing with --pooling-enabled when starting two endpoints.

ENOTEMPTY Error

If you encounter an npm error:

ENOTEMPTY Error: rmdir /path/to/directory

Ensure that the target directory is empty or manually delete the directory and try again. This usually occurs when npm fails to uninstall a package.

Summary

This MCP server provides powerful tools and integration capabilities for sending SMS messages via Twilio, supports status callback handling, and can be easily run via npx. We hope the above documentation helps you configure and use it smoothly!