MCP Twilio SMS

MCP server that lets Claude send SMS text messages via Twilio. Single-file Python server (server.py) exposing two MCP tools: send_sms and get_sms_status.

How It Works

Claude → send_sms(to, body)              → Twilio API → SMS delivered
Claude → get_sms_status(message_sid)     → Twilio API → delivery status

The server speaks MCP over stdio. Claude (Code or Desktop) launches it as a subprocess, Twilio credentials are supplied via environment variables, and the two tools wrap the official twilio Python SDK.

Tools

send_sms

Send a text message. Parameters:

• to — Recipient phone number in E.164 format (e.g. +33612345678)

• body — Message text (max 1600 characters)

• from_number — Optional sender override (default: TWILIO_PHONE_NUMBER env var)

Returns message_sid, status, to, from, and segments.

get_sms_status

Check delivery status of a sent message by its message_sid. Returns one of: queued, sending, sent, delivered, failed, or undelivered (plus error_code/error_message on failure).

Setup

1. Prerequisites

• uv — install with curl -LsSf https://astral.sh/uv/install.sh | sh

• Python ≥ 3.11 (uv will fetch it if missing)

• A Twilio account

2. Get Twilio credentials

From the Twilio Console:

1. Copy your Account SID and Auth Token from the dashboard.

2. Get an SMS-capable phone number (Console → Phone Numbers → Buy a number, or use the trial number). It must be in E.164 format, e.g. +1234567890.

Trial accounts can only send SMS to phone numbers you have verified in the Console (Verified Caller IDs), and messages are prefixed with a trial notice. Upgrade the account to remove both limits.

3. Install dependencies

git clone git@github.com:sebastienfi/mcp-twilio-sms.git
cd mcp-twilio-sms
uv sync

4. Configure secrets

Create a secrets file (shared with other MCP servers) and lock it down:

mkdir -p ~/.config/mcp
cat > ~/.config/mcp/secrets.env <<'EOF'
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your-auth-token
TWILIO_PHONE_NUMBER=+1234567890
EOF
chmod 600 ~/.config/mcp/secrets.env

See .env.example for the full list of variables.

5. Verify it runs

# Load secrets and start the server (Ctrl-C to stop — it waits for a client on stdio)
set -a; source ~/.config/mcp/secrets.env; set +a
uv run python server.py

The server has no console UI; it waits for an MCP client on stdio. Register it with Claude (below) to actually use it.

6. Register with Claude Code

Add to ~/.claude.json under mcpServers (use absolute paths):

{
  "twilio-sms": {
    "command": "/bin/bash",
    "args": [
      "-c",
      "set -a; source /Users/you/.config/mcp/secrets.env; set +a; exec /opt/homebrew/bin/uv run --directory /path/to/mcp-twilio-sms python server.py"
    ]
  }
}

Or with the CLI:

claude mcp add twilio-sms -- /bin/bash -c \
  "set -a; source ~/.config/mcp/secrets.env; set +a; exec uv run --directory $(pwd) python server.py"

Restart Claude Code, then confirm with /mcp that twilio-sms is connected.

7. Register with Claude Desktop

Add the same block to claude_desktop_config.json:

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

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Use absolute paths for both uv and the project directory, then restart Claude Desktop.

Running directly

server.py carries PEP 723 inline metadata, so it runs standalone without uv sync:

uv run --script server.py

Development

uv sync                   # Install dependencies
uv run python server.py   # Run the MCP server (stdio transport)

No test suite or linter is configured.

License

MIT