# 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:
```env
# 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:**
```json
{
"to": "+11234567890",
"message": "Your message here"
}
```
**Response:**
```json
{
"success": true,
"message": "Message sent successfully",
"messageSid": "SM...",
"to": "+11234567890",
"from": "+1234567890"
}
```
### `POST /send-greeting`
Send a greeting message for special occasions
**Request Body:**
```json
{
"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`
```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](https://railway.app)
2. Set environment variables in Railway dashboard
3. Deploy automatically
### Option 2: Render
1. Connect your repo to [Render](https://render.com)
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
```bash
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
```bash
# 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
```bash
# 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](https://console.twilio.com)
- 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.
