mustafa-boorenie/twilio_sms_mcp

Twilio SMS Server

A versatile SMS service that can run as both a Model Context Protocol (MCP) server for Claude Desktop and as a standalone REST API for cloud deployment.

🚀 Two Deployment Modes

1. MCP Server Mode (Local with Claude Desktop)

Enables Claude and other AI assistants to send SMS messages through the Model Context Protocol.

2. Web API Mode (Cloud Deployment)

Standalone REST API that can be deployed to any cloud platform for web applications.

✨ Features

• 📱 Send SMS messages via Twilio
• 🌐 REST API endpoints for web integration
• 🔨 MCP server for Claude Desktop integration
• 📝 Pre-built prompts for common messaging scenarios
• 🔒 Secure handling of Twilio credentials
• 🐳 Docker support for easy deployment
• ☁️ Cloud deployment ready

📋 Requirements

• Node.js >= 18
• Twilio account with SMS capabilities
• Environment variables for Twilio credentials

⚙️ Environment Setup

Create a .env file in the project root:

# Twilio Configuration (Required)
ACCOUNT_SID=your_twilio_account_sid_here
AUTH_TOKEN=your_twilio_auth_token_here
FROM_NUMBER=+1234567890

# Server Configuration (Optional, defaults to 3000)
PORT=3000

🚀 Installation & Usage

Local Development

```bash

Install dependencies

npm install

Build the project

npm run build

Run as MCP server (for Claude Desktop)

npm run start:mcp

Run as Web API server

npm run start:web

Development mode (rebuilds and starts web server)

npm run dev:web ```

🌐 Web API Endpoints

When running in Web API mode, the following endpoints are available:

GET /

API documentation and usage examples

GET /health

Health check endpoint

POST /send-sms

Send an SMS message

Request Body:

{
  "to": "+11234567890",
  "message": "Your message here"
}

Response:

{
  "success": true,
  "message": "Message sent successfully",
  "messageSid": "SM...",
  "to": "+11234567890",
  "from": "+1234567890"
}

POST /send-greeting

Send a greeting message for special occasions

Request Body:

{
  "to": "+11234567890",
  "occasion": "birthday",
  "customMessage": "Optional custom message"
}

🖥️ Claude Desktop Configuration (MCP Mode)

To use this server with Claude Desktop, add the following to your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "twilio": {
      "command": "npx",
      "args": [
        "-y",
        "@yiyang.1i/sms-mcp-server"
      ],
      "env": {
        "ACCOUNT_SID": "your_account_sid",
        "AUTH_TOKEN": "your_auth_token",
        "FROM_NUMBER": "your_twilio_number"
      }
    }
  }
}

After updating the configuration, restart Claude Desktop. If connected successfully, you should see Twilio under the 🔨 menu.

☁️ Cloud Deployment

Option 1: Railway

1. Connect your GitHub repository to Railway
2. Set environment variables in Railway dashboard
3. Deploy automatically

Option 2: Render

1. Connect your repo to Render
2. Create a new Web Service
3. Build command: npm install && npm run build
4. Start command: npm run start:web
5. Add environment variables

Option 3: Heroku

heroku create your-app-name
heroku config:set ACCOUNT_SID=your_sid
heroku config:set AUTH_TOKEN=your_token  
heroku config:set FROM_NUMBER=your_number
git push heroku main

Option 4: Docker

# Build Docker image
docker build -t twilio-sms-server .

# Run container
docker run -p 3000:3000 \
  -e ACCOUNT_SID=your_sid \
  -e AUTH_TOKEN=your_token \
  -e FROM_NUMBER=your_number \
  twilio-sms-server

🧪 Testing the API

Local Testing

# Start the server
npm run start:web

# Test health endpoint
curl http://localhost:3000/health

# Send a test SMS
curl -X POST http://localhost:3000/send-sms \
  -H "Content-Type: application/json" \
  -d '{"to": "+1234567890", "message": "Hello from the API!"}'

# Send a greeting
curl -X POST http://localhost:3000/send-greeting \
  -H "Content-Type: application/json" \
  -d '{"to": "+1234567890", "occasion": "birthday"}'

💬 Example Interactions with Claude (MCP Mode)

Here are some natural ways to interact with the server through Claude:

1. Simple SMS:

Send a text message to +11234567890 saying "Don't forget about dinner tonight!"

2. Creative SMS:

Write a haiku about autumn and send it to my number +11234567890

3. Greeting Messages:

Send a birthday greeting to +11234567890

📝 Scripts Reference

• npm run build - Build TypeScript to JavaScript
• npm run start:mcp - Start MCP server mode
• npm run start:web - Start web API server mode
• npm run dev:web - Development mode (rebuild + start web server)
• npm run watch - Watch TypeScript files for changes

⚠️ Important Notes

1. Phone Number Format: All phone numbers must be in E.164 format (e.g., +11234567890)
2. Twilio Trial Accounts: Can only send messages to verified phone numbers
3. Rate Limits: Be aware of your Twilio account's rate limits and pricing
4. Security: Keep your Twilio credentials secure and never commit them to version control
5. Environment Variables: Use .env file for local development, set via platform for cloud deployment

🐛 Troubleshooting

Common Errors and Solutions:

1. "Phone number must be in E.164 format"

   • Ensure phone number starts with "+" and includes country code

2. "Invalid credentials" / "accountSid must start with AC"

   • Verify your ACCOUNT_SID and AUTH_TOKEN from Twilio Console
   • Ensure environment variables are properly loaded

3. "Invalid 'To' Phone Number"

   • For trial accounts: Verify the destination number in Twilio Console
   • For paid accounts: Ensure the number format is correct

4. "Environment variable is required"

   • Check that .env file exists and contains all required variables
   • For cloud deployment, ensure environment variables are set in platform settings

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines before submitting pull requests.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔐 Security

Please do not include any sensitive information (like phone numbers or Twilio credentials) in GitHub issues or pull requests.