Twilio MCP Server (Docker Edition with Auth Token Support)

🚀 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

2. Create .env File

Create a .env file with your Twilio credentials:

3. Build and Run

The server will be available at http://localhost:3010 via SSE transport.

4. View Logs

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):

API Key Mode:

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:

Or if running on a remote server:

🐳 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

💾 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

🐛 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:

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:

📚 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

• MCP Protocol Issues: Refer to the Model Context Protocol documentation

• Docker Issues: Check the Docker documentation

• This Fork: Open an issue in this repository

🔗 Related Links

• Twilio Console

• Twilio API Keys

• Model Context Protocol

• mcp-proxy