mcpengine/servers/twilio/README.md

# Twilio MCP Server

Complete MCP server for Twilio communications platform. Send SMS/MMS, make voice calls, verify phone numbers, manage conversations, and validate phone data — all via AI.

## Features

- 📱 **Messaging** - Send/receive SMS and MMS with media support
- 📞 **Voice** - Initiate and manage voice calls with TwiML
- 📋 **Phone Numbers** - Manage purchased numbers and webhook configuration
- 🎙️ **Recordings** - Access call recordings and transcriptions
- 💬 **Conversations** - Multi-channel messaging threads (SMS, WhatsApp, chat)
- 🔐 **Verify** - Phone/email verification and 2FA
- 🔍 **Lookups** - Phone number validation and carrier lookup

## Installation

```bash
npm install
npm run build
```

## Environment Variables

| Variable | Required | Description | Example |
|----------|----------|-------------|---------|
| `TWILIO_ACCOUNT_SID` | ✅ | Twilio Account SID | `ACxxxxxxxxxxxxxxx` |
| `TWILIO_AUTH_TOKEN` | ✅ | Twilio Auth Token | `your_auth_token` |

## Getting Your Credentials

1. Log in to Twilio Console: https://console.twilio.com/
2. Your **Account SID** is displayed on the dashboard
3. Click **Show** next to **Auth Token** to reveal it
4. Set environment variables:

```bash
export TWILIO_ACCOUNT_SID='ACxxxxxxxxxxxxxxx'
export TWILIO_AUTH_TOKEN='your_auth_token_here'
```

**⚠️ WARNING:** Keep your Auth Token secret! It provides full account access.

## Required API Permissions

- **Full Account Access** (default for Auth Token)

For production, consider using API Keys with scoped permissions instead of Auth Token.

## Usage

### Stdio Mode (Default)

```bash
npm start
# or
node dist/main.js
```

### With MCP Client

Add to your MCP settings:

```json
{
  "mcpServers": {
    "twilio": {
      "command": "node",
      "args": ["/path/to/servers/twilio/dist/main.js"],
      "env": {
        "TWILIO_ACCOUNT_SID": "ACxxxxxxxxxxxxxxx",
        "TWILIO_AUTH_TOKEN": "your_auth_token_here"
      }
    }
  }
}
```

## Available Tools (21+)

### Messaging (4)
- `list_messages` - List SMS/MMS with pagination and filters
- `get_message` - Get message details by SID
- `send_message` - Send SMS/MMS with media support
- `delete_message` - Delete message record

### Voice (5)
- `list_calls` - List calls with status/duration filters
- `get_call` - Get call details by SID
- `make_call` - Initiate outbound call with TwiML
- `update_call` - Cancel or hang up in-progress call
- `delete_call` - Delete call record

### Phone Numbers (4)
- `list_phone_numbers` - List purchased numbers
- `get_phone_number` - Get number configuration
- `update_phone_number` - Update webhook URLs and settings
- `delete_phone_number` - Release number from account

### Conversations (6)
- `twilio_list_conversations` - List conversation threads
- `twilio_get_conversation` - Get conversation details
- `twilio_create_conversation` - Create new conversation
- `twilio_add_participant` - Add user to conversation
- `twilio_list_conversation_messages` - List messages in thread
- `twilio_send_conversation_message` - Send message in conversation

### Verify (4)
- `twilio_send_verification` - Send verification code (SMS/voice/email)
- `twilio_check_verification` - Verify user-entered code
- `twilio_create_verify_service` - Create verification service
- `twilio_list_verify_services` - List verification services

### Lookups (2)
- `twilio_lookup_phone_number` - Get carrier info and validate number
- `twilio_validate_phone_number` - Quick validation (free)

### Recordings (2-3)
- Recording and transcription management tools

## Coverage Manifest

**Total Twilio API endpoints:** ~500 (Messaging, Voice, Video, Verify, Conversations, Serverless, Flex, etc.)  
**Tools implemented:** 21+  
**Coverage:** ~4%

### Intentionally Skipped:
- **Video** - Video calling APIs (complex real-time, better via SDK)
- **Flex** - Contact center platform (UI-heavy, admin configuration)
- **Serverless** - Functions/Assets deployment (better via CLI)
- **Studio** - Visual workflow builder (drag-drop UI tool)
- **TaskRouter** - Call routing/queueing (complex enterprise feature)
- **Sync** - Real-time data sync (runtime SDK feature)
- **Notify** - Push notifications (deprecated in favor of Conversations)
- **Autopilot** - AI assistant builder (UI-based configuration)
- **Programmable Wireless** - IoT SIM management (niche use case)
- **Proxy** - Anonymous phone forwarding (advanced feature)

Focus is on core communications: messaging, voice, verification, conversations, and phone number management — the 80% of use cases.

## Architecture

- **main.ts** - Entry point with env validation and graceful shutdown
- **server.ts** - MCP server class with lazy-loaded tool modules
- **tools/** - Domain-organized tool files (messaging, voice, phone_numbers, recordings, conversations, verify, lookups)
- **Twilio SDK** - Official `twilio` npm package for API calls

## Common Use Cases

- **2FA/OTP** - Use Verify API for phone/email verification
- **SMS Notifications** - Send alerts, reminders, confirmations
- **Voice Calls** - Automated calls, IVR systems, click-to-call
- **Customer Support** - Multi-channel conversations (SMS, WhatsApp, chat)
- **Phone Validation** - Validate user input, check carrier type
- **Call Recording** - Record and transcribe calls for compliance

## License

MIT