Twilio MCP Server (Docker Edition with Auth Token Support)

# Twilio MCP Server (Docker Edition with Auth Token Support) <p align="center"> A Model Context Protocol (MCP) server for the Twilio API, packaged for easy deployment via Docker with mcp-proxy for SSE transport. This fork adds support for Auth Token authentication in addition to the standard API Key authentication. </p> ## 🚀 Features - **Dual Authentication Support**: Works with both Twilio API Keys and Auth Tokens - **Docker Deployment**: Pre-configured Docker setup with mcp-proxy for SSE transport - **Multiple Twilio Services**: Supports Twilio API v2010, Messaging v1, Voice v1, and Studio v2 - **Property Name Sanitization**: Includes automatic patching to ensure Claude API compatibility - **Unraid Compatible**: Ready for deployment on Unraid or any Docker environment - **Easy Configuration**: Simple `.env` file configuration - **Auto-restart**: Container automatically restarts if it crashes ## 📋 What's Different in This Fork The official `@twilio-alpha/mcp` package requires API Key authentication (credentials starting with `SK`). However, many Twilio accounts may not have API Keys configured. This fork modifies the authentication layer to accept **Auth Token authentication** as an alternative: - **API Key Format**: `AccountSid/ApiKey:ApiSecret` (original) - **Auth Token Format**: `AccountSid/AuthToken` (new) When using Auth Token format, the server uses the AccountSid as the username and the Auth Token as the password for HTTP Basic authentication with the Twilio API. ### Modified Files - `packages/mcp/src/utils/args.ts`: Updated to parse and validate both authentication formats ## 📦 Prerequisites - Docker and Docker Compose - Twilio account credentials: - Account SID (starts with `AC`) - Auth Token OR API Key/Secret pair ## 🚀 Quick Start ### 1. Clone and Configure ```bash git clone <this-repo> cd twilio-mcp ``` ### 2. Create `.env` File Create a `.env` file with your Twilio credentials: ```env # Required TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx TWILIO_AUTH_TOKEN=your_auth_token_here # Optional (if using API Key authentication) TWILIO_API_KEY=SKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx TWILIO_API_SECRET=your_api_secret_here ``` ### 3. Build and Run ```bash docker compose build docker compose up -d ``` The server will be available at `http://localhost:3010` via SSE transport. ### 4. View Logs ```bash docker compose logs -f twilio-mcp ``` You should see: `starting server on port 3010` ## ⚙️ Configuration ### Authentication Modes The `start-twilio-mcp.sh` script determines which authentication mode to use: **Auth Token Mode** (default): ```bash exec npx -y @twilio-alpha/mcp "${TWILIO_ACCOUNT_SID}/${TWILIO_AUTH_TOKEN}" \ --services "twilio_api_v2010,twilio_messaging_v1,twilio_voice_v1,twilio_studio_v2" ``` **API Key Mode**: ```bash exec npx -y @twilio-alpha/mcp "${TWILIO_ACCOUNT_SID}/${TWILIO_API_KEY}:${TWILIO_API_SECRET}" \ --services "twilio_api_v2010,twilio_messaging_v1,twilio_voice_v1,twilio_studio_v2" ``` ### Available Services You can customize which Twilio services to load by modifying the `--services` parameter in `start-twilio-mcp.sh`: - `twilio_api_v2010`: Core Twilio REST API (accounts, calls, messages, recordings, etc.) - `twilio_messaging_v1`: Messaging services (messaging services, A2P, brand registrations, etc.) - `twilio_voice_v1`: Voice services (BYOC trunks, connection policies, dialing permissions, etc.) - `twilio_studio_v2`: Studio flows and executions ## 🔌 Connecting to Claude Code Add this server to your Claude Code MCP configuration: ```json { "mcpServers": { "twilio": { "url": "http://localhost:3010/sse" } } } ``` Or if running on a remote server: ```json { "mcpServers": { "twilio": { "url": "http://YOUR_SERVER_IP:3010/sse" } } } ``` ## 🐳 Docker Compose Configuration The `docker-compose.yml` includes: - **Port mapping**: `3010:3010` for SSE transport - **Environment variables**: Loaded from `.env` file - **External network**: `mcp_network` (create if needed) - **Auto-restart policy**: `unless-stopped` - **Command**: Uses mcp-proxy to wrap the stdio server ### Creating the Network ```bash docker network create mcp_network ``` ## 💾 Deployment on Unraid 1. SSH into your Unraid server 2. Create directory: `mkdir -p /mnt/user/appdata/twilio-mcp` 3. Place all files in `/mnt/user/appdata/twilio-mcp/` 4. Create `.env` file with your credentials 5. Ensure `mcp_network` exists: `docker network create mcp_network` 6. Navigate to directory: `cd /mnt/user/appdata/twilio-mcp` 7. Run: `docker compose up -d` ## 🔧 Technical Details ### Property Name Sanitization The `patch-load-tools.sh` script automatically patches the OpenAPI MCP server during Docker build to sanitize property names for Claude API compatibility: - Removes invalid characters (replaces with `_`) - Ensures names don't start with numbers - Limits length to 64 characters - Runs automatically during `docker build` This ensures all Twilio API parameters work correctly with Claude's MCP implementation. ### Authentication Flow 1. The `start-twilio-mcp.sh` script receives credentials as environment variables 2. It passes them to `@twilio-alpha/mcp` in the appropriate format 3. The modified `args.ts` parser detects the format: - If contains `:`, treats as API Key format (`apiKey:apiSecret`) - If no `:`, treats as Auth Token format (just the token) 4. For Auth Token mode: - `apiKey` is set to `AccountSid` - `apiSecret` is set to the Auth Token - Validation accepts `AC` prefix (AccountSid) in addition to `SK` prefix (API Key) 5. Credentials are passed to the Twilio client for HTTP Basic authentication ### mcp-proxy Wrapper This deployment uses `mcp-proxy` to convert the stdio-based MCP server to SSE transport: - **Stdio Transport**: The original `@twilio-alpha/mcp` communicates via stdin/stdout - **SSE Transport**: mcp-proxy wraps it and exposes at `http://localhost:3010/sse` - **Benefits**: Allows remote access and integration with web-based tools ### File Structure ``` twilio-mcp/ ├── Dockerfile # Docker image definition ├── docker-compose.yml # Docker Compose configuration ├── .env # Environment variables (create this) ├── start-twilio-mcp.sh # Wrapper script for launching server ├── patch-load-tools.sh # Property name sanitization script ├── packages/ │ ├── mcp/ # Main MCP server package │ │ ├── src/ │ │ │ ├── index.ts # Main entry point │ │ │ ├── main.ts # Server initialization │ │ │ ├── server.ts # Server implementation │ │ │ └── utils/ │ │ │ └── args.ts # ⭐ Modified: Auth Token support │ │ └── ... │ └── openapi-mcp-server/ # OpenAPI MCP implementation │ ├── src/ │ │ ├── server.ts # OpenAPI server implementation │ │ └── utils/ │ │ └── loadTools.ts # Tool loading (patched for sanitization) │ └── ... └── README.md # This file ``` ## 🐛 Troubleshooting ### Container Crashes Immediately Check logs: `docker compose logs twilio-mcp` Common issues: - **Missing environment variables**: Ensure `.env` file exists and contains all required variables - **Incorrect credentials**: Verify Account SID and Auth Token are correct - **Network doesn't exist**: Create with `docker network create mcp_network` - **Port conflict**: Port 3010 is already in use ### Authentication Errors (401) - Verify your Account SID starts with `AC` - Verify your Auth Token is correct (not the API Key) - Test credentials with curl: ```bash curl -X GET "https://api.twilio.com/2010-04-01/Accounts/YOUR_ACCOUNT_SID.json" \ -u "YOUR_ACCOUNT_SID:YOUR_AUTH_TOKEN" ``` If this returns account data, your credentials are correct. ### Connection Issues from Claude Code - Ensure container is running: `docker ps | grep twilio-mcp` - Verify port 3010 is accessible: `curl http://localhost:3010/sse` - Check network connectivity - Verify the URL in Claude Code config matches your setup - Try restarting Claude Code after configuration changes ### Environment Variables Not Loading - Ensure `.env` file is in the same directory as `docker-compose.yml` - Check environment variables in container: `docker exec twilio-mcp-server env | grep TWILIO` - Restart container after `.env` changes: `docker compose down && docker compose up -d` ### Build Cache Issues If changes to source files aren't being picked up: ```bash docker compose down docker compose build --no-cache docker compose up -d ``` ## 📚 Available Twilio Operations Once connected, you'll have access to hundreds of Twilio API operations across all configured services: ### API v2010 - Manage accounts, subaccounts, and credentials - Send/receive calls and messages - Manage phone numbers and addresses - Access call recordings and transcriptions - Configure applications and queues ### Messaging v1 - Create and manage messaging services - Configure alpha senders and channel senders - Register A2P brands and campaigns - Manage toll-free verifications - Handle phone number configuration ### Voice v1 - Configure BYOC trunks - Manage connection policies and targets - Set dialing permissions by country - Configure IP records and source IP mappings ### Studio v2 - Create and manage Studio flows - Trigger flow executions - Retrieve execution history and steps - Manage flow revisions ## 🔒 Security Recommendations From the Twilio ETI team: > To guard against injection attacks that may allow untrusted systems access to your Twilio data, we advise users to avoid installing or running any community MCP servers alongside official ones. Doing so helps ensure that only trusted MCP servers have access to tools interacting with your Twilio account. Additional recommendations: - Store `.env` file securely and never commit it to version control - Use API Keys with restricted permissions when possible - Regularly rotate your Auth Tokens and API Keys - Monitor your Twilio usage for unusual activity - Run the container on a private network when possible ## 📄 License This is a fork of `@twilio-alpha/mcp` which is licensed under the ISC License. Please refer to the original project for detailed licensing information. ## 🙏 Credits - Original `@twilio-alpha/mcp` package by Twilio Labs - Modified for Auth Token support and Docker deployment by the community - `mcp-proxy` for SSE transport support ## 🤝 Contributing Contributions are welcome! If you encounter issues or have improvements: 1. Check existing issues 2. Create a detailed bug report or feature request 3. Submit pull requests with clear descriptions 4. Include tests for new functionality ## 📞 Support - **Twilio API Issues**: Consult the [Twilio documentation](https://www.twilio.com/docs) - **MCP Protocol Issues**: Refer to the [Model Context Protocol documentation](https://modelcontextprotocol.io/) - **Docker Issues**: Check the [Docker documentation](https://docs.docker.com/) - **This Fork**: Open an issue in this repository ## 🔗 Related Links - [Twilio Console](https://console.twilio.com/) - [Twilio API Keys](https://www.twilio.com/docs/iam/api-keys) - [Model Context Protocol](https://modelcontextprotocol.io/) - [mcp-proxy](https://github.com/modelcontextprotocol/servers)