Skip to main content
Glama
twilio-mcp-server

twilio-mcp-server

by skbhati199

twilio-mcp-server

An MCP (Model Context Protocol) server that exposes Twilio SMS sending as MCP tools, protected by OAuth 2.0 (client_credentials grant), and reachable remotely through a Cloudflare Tunnel (cloudflared).

MCP Client  --Bearer token-->  [cloudflared tunnel]  -->  Express app :3020  -->  Twilio API
                                                             |-- POST /oauth/token   (get access token)
                                                             |-- POST /mcp           (MCP tools, needs Bearer token)
                                                             |-- GET  /health

1. Install

cd twilio-mcp-server
npm install
cp .env.example .env

Edit .env:

PORT=3020
TRANSPORT=http

# OAuth 2.0 credentials for THIS server (make up your own strong values)
OAUTH_CLIENT_ID=demo-client-id
OAUTH_CLIENT_SECRET=demo-client-secret-change-me
OAUTH_JWT_SECRET=super-secret-signing-key-change-me
OAUTH_TOKEN_TTL_SECONDS=3600

# Twilio account credentials (from twilio.com/console)
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_twilio_auth_token
TWILIO_FROM_NUMBER=+15017122661

Related MCP server: twilio-mcp

2. Build & run

npm run build
npm start

You should see:

twilio-mcp-server v1.0.0
MCP endpoint:   http://localhost:3020/mcp  (requires Bearer token)
OAuth token:    POST http://localhost:3020/oauth/token
Health check:   GET  http://localhost:3020/health

3. How the OAuth 2.0 flow works

This server implements the client_credentials grant (machine-to-machine — no user login screen):

  1. A client calls POST /oauth/token with its client_id + client_secret.

  2. The server verifies them and returns a signed, short-lived JWT access_token.

  3. The client calls POST /mcp with Authorization: Bearer <access_token>.

  4. The server verifies the token signature/expiry before handling any MCP request.

Get a token:

curl -X POST http://localhost:3020/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "demo-client-id",
    "client_secret": "demo-client-secret-change-me"
  }'

Response:

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "sms:send"
}

Call the MCP endpoint with it:

curl -X POST http://localhost:3020/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer <access_token>" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Note: Twilio itself doesn't support OAuth for its SMS API — Twilio authenticates server-to-server using TWILIO_ACCOUNT_SID + TWILIO_AUTH_TOKEN. The OAuth 2.0 layer here protects access to this MCP server; the server then uses your Twilio credentials internally to actually send the SMS.

4. Tools exposed

Tool

Description

twilio_send_sms

Sends an SMS. Args: to (E.164 phone number), body (message text, max 1600 chars)

twilio_get_sms_status

Looks up delivery status of a previously sent message by message_sid

5. Expose it publicly with cloudflared (Cloudflare Tunnel)

Install cloudflared (one-time):

# macOS
brew install cloudflare/cloudflare/cloudflared

# Debian/Ubuntu
curl -L --output cloudflared.deb https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
sudo dpkg -i cloudflared.deb

# Windows
winget install --id Cloudflare.cloudflared

Start the MCP server (port 3020), then in a separate terminal run a quick tunnel (no Cloudflare account needed, great for testing):

cloudflared tunnel --url http://localhost:3020

Cloudflared prints a public URL like:

https://random-words-here.trycloudflare.com

Your MCP endpoint is now reachable at:

https://random-words-here.trycloudflare.com/mcp

and the OAuth token endpoint at:

https://random-words-here.trycloudflare.com/oauth/token

Persistent named tunnel (production)

For a stable subdomain instead of a random one each time:

cloudflared tunnel login
cloudflared tunnel create twilio-mcp-server
cloudflared tunnel route dns twilio-mcp-server mcp.yourdomain.com

Create ~/.cloudflared/config.yml:

tunnel: twilio-mcp-server
credentials-file: /root/.cloudflared/<tunnel-id>.json

ingress:
  - hostname: mcp.yourdomain.com
    service: http://localhost:3020
  - service: http_status:404

Run it:

cloudflared tunnel run twilio-mcp-server

Now https://mcp.yourdomain.com/mcp is your permanent MCP endpoint.

6. Connect an MCP client through the tunnel

A ready-made example client is in client-example/mcpClient.mjs:

cd client-example
npm install

MCP_SERVER_URL=https://random-words-here.trycloudflare.com/mcp \
OAUTH_TOKEN_URL=https://random-words-here.trycloudflare.com/oauth/token \
OAUTH_CLIENT_ID=demo-client-id \
OAUTH_CLIENT_SECRET=demo-client-secret-change-me \
TO_NUMBER=+919876543210 \
MESSAGE_BODY="Hello from the tunnel!" \
node mcpClient.mjs

This will:

  1. Fetch an OAuth access token from the tunnel URL

  2. Connect to the MCP server through the tunnel

  3. List available tools

  4. Call twilio_send_sms to actually send a message

7. Testing with MCP Inspector

npx @modelcontextprotocol/inspector

Point it at http://localhost:3020/mcp (or your tunnel URL), set the Authorization header to Bearer <token> obtained from /oauth/token, and call the tools interactively.

8. Notes on Twilio trial accounts

If you're using a Twilio trial account:

  • You can only send SMS to phone numbers you've verified in the Twilio console (Console → Phone Numbers → Verified Caller IDs).

  • Messages will be prefixed with "Sent from your Twilio trial account".

  • Upgrade the account to send to any number.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      MCP server for sending SMS via the SMSPM API. Send transactional SMS from Claude Desktop, Cursor, Windsurf, Cline, or any MCP client.
      1
      32 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A least-privilege, send-only MCP server for WhatsApp, backed by Meta's official WhatsApp Cloud API. It exposes tools to send text messages and pre-approved templates.
      8 npm
      MIT