jake/clawdbot-workspace
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
clawdbot-workspace/twilio-mcp
History

README.md

@busybee/twilio-mcp

The Twilio MCP that doesn't suck.

npm version License: MIT MCP Protocol

A workflow-first Twilio integration for the Model Context Protocol (MCP). Built for Claude and other AI assistants that actually understand what you're trying to do — not just dump 400+ raw API endpoints in your context window.

🔥 Why This Exists

Twilio's official MCP (@twilio-alpha/mcp) is auto-generated from OpenAPI specs. It dumps 400+ raw API endpoints as individual tools, requires manual --services filtering just to be usable, burns through your context window, and has zero understanding of actual workflows.

We built the alternative.

Instead of raw CRUD, we give you compound workflow tools like twilio_campaign_launch, twilio_build_ivr, and twilio_number_hunt — tools that actually do things. We lazy-load only what you need. We ship 17 rich HTML dashboards (MCP Apps) for visual exploration. And we annotate every tool with safety tiers so your AI knows what's safe to run autonomously.

This is the Twilio MCP for people who want to ship, not wrestle with API docs.

🆚 How We Stack Up

Feature Official Twilio MCP This MCP
Tool philosophy Raw API endpoints (1:1 OpenAPI mapping) Workflow-oriented compound tools
Default tool count 400+ (requires --services filtering) 5 always-loaded + lazy packs
Context efficiency 28.5% more cache reads (their own benchmark) Minimal — only loads what you need
Visual UI None 17 MCP Apps with rich HTML dashboards
Tool safety No hints, no annotations Green/Yellow/Red safety tiers with cost/destructive annotations
Lazy loading Nope — all or manually filtered Auto-detects intent and loads packs on-demand
Workflow awareness Zero Built-in: campaigns, IVRs, number provisioning, compliance flows

🚀 Quick Start

1. Install via npx (no installation needed)

npx @busybee/twilio-mcp

Or install globally:

npm install -g @busybee/twilio-mcp

2. Configure Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "twilio": {
      "command": "npx",
      "args": [
        "-y",
        "@busybee/twilio-mcp"
      ],
      "env": {
        "TWILIO_ACCOUNT_SID": "your_account_sid",
        "TWILIO_API_KEY": "your_api_key",
        "TWILIO_API_SECRET": "your_api_secret"
      }
    }
  }
}

Where to get credentials:

3. Restart Claude and go

Say things like:

  • "Show me my Twilio dashboard"
  • "Send an SMS to +15551234567 saying 'Hello from Claude!'"
  • "What messaging tools are available?"
  • "Launch an SMS campaign to these 50 numbers"
  • "Build an IVR for customer support"

📦 Tool Catalog

🟢 Tier 1 — Always Loaded (5 tools)

These load instantly on startup. They help you navigate, send quick messages, and explore the rest.

Tool Type Description
twilio_explore 🎯 Navigator Discover available packs and load them on-demand. Your gateway to everything.
twilio_dashboard 📊 MCP App Visual dashboard of your account: balance, usage, message/call stats, active numbers.
twilio_quick_send 📱 Messaging Send an SMS/MMS/WhatsApp message. Auto-validates numbers and picks a sender.
twilio_quick_call 📞 Voice Place an outbound call. Say a message, connect to another number, or record.
twilio_lookup 🔍 Intelligence Get phone number intel: validation, carrier, line type, caller name (3 depth levels).

Example:

> twilio_dashboard

→ Renders a beautiful HTML dashboard with your balance, active numbers, recent message/call activity.

📱 Messaging Pack (6 tools)

Load with: twilio_explore category=messaging (or ask for "SMS campaign" / "WhatsApp" / etc.)

Tool Type Description
twilio_campaign_launch 🚀 MCP App Launch a bulk SMS/MMS campaign to a list of numbers with throttling and retry.
twilio_conversation_thread 💬 MCP App View an SMS conversation thread with someone as a rich chat UI.
twilio_template_create 📝 Workflow Create a reusable message template with variables (e.g., "Hi {{name}}!").
twilio_auto_responder 🤖 Workflow Set up keyword-based auto-replies (e.g., reply "HOURS" → "We're open 9-5").
twilio_schedule_message ⏰ Workflow Schedule a message to send at a specific time (using Messaging Services).
twilio_message_log 📋 MCP App Visual log of recent messages with filters, status badges, and sparklines.

Use case: "Launch a campaign to these 100 customers reminding them about the sale" → auto-loads messaging pack, uses twilio_campaign_launch.

📞 Voice Pack (7 tools)

Load with: twilio_explore category=voice

Tool Type Description
twilio_build_ivr 🌳 MCP App Build an interactive voice response (IVR) phone tree with menu options and routing.
twilio_call_blast 📣 Workflow Place simultaneous calls to a list (announcements, alerts, political campaigns).
twilio_record_greeting 🎙️ Workflow Record or generate a voice greeting for voicemail/IVR.
twilio_voicemail_box 📥 MCP App Set up a voicemail system with transcription and notifications.
twilio_conference_room 🎤 Workflow Create a conference call room with PIN, recording, hold music.
twilio_call_analytics 📊 MCP App Visual analytics dashboard for call volume, duration, outcomes.
twilio_call_transcribe 📝 Workflow Transcribe a recorded call using Twilio's speech-to-text.

Use case: "Build an IVR for our support line — press 1 for sales, 2 for support" → auto-loads voice pack, uses twilio_build_ivr.

🔍 Number Intelligence Pack (4 tools)

Load with: twilio_explore category=intelligence

Tool Type Description
twilio_deep_scan 🕵️ MCP App Deep intelligence scan: fraud score, sim swap risk, caller reputation, everything.
twilio_fraud_check ⚠️ Workflow Quick fraud/scam check on a number before calling or messaging.
twilio_number_validate_batch ✅ Workflow Validate a list of phone numbers in bulk (check format, carrier, line type).
twilio_identity_verify 🆔 Workflow Verify someone's identity by cross-checking number ownership and reputation.

Use case: "Is this number safe to call? Check for fraud" → auto-loads intelligence pack, runs twilio_fraud_check.

🔐 Verify & Security Pack (4 tools)

Load with: twilio_explore category=verify

Tool Type Description
twilio_otp_send 🔑 Workflow Send a one-time passcode (OTP) via SMS or voice for 2FA.
twilio_otp_check ✅ Workflow Verify an OTP that a user entered.
twilio_auth_flow_setup 🔐 MCP App Set up a complete 2FA flow for your app (send + verify + retry logic).
twilio_silent_network_auth 📡 Workflow Silent Network Authentication (SNA) — verify a phone without sending a code.

Use case: "Send a 2FA code to this user" → auto-loads verify pack, uses twilio_otp_send.

📞 Phone Numbers Pack (5 tools)

Load with: twilio_explore category=numbers

Tool Type Description
twilio_number_hunt 🎯 MCP App Search available numbers by area code, pattern, or features (toll-free, SMS, voice).
twilio_number_provision 🛒 Workflow Buy a phone number (with confirmation prompt).
twilio_number_inventory 📋 MCP App Visual inventory of your owned numbers with usage stats and capabilities.
twilio_number_configure ⚙️ Workflow Configure a number's webhooks, friendly name, voice URL, SMS URL.
twilio_number_release 🗑️ Workflow Release (delete) a phone number you no longer need. 🔴 Destructive!

Use case: "Find me a 415 area code number with SMS" → auto-loads numbers pack, uses twilio_number_hunt.

🎨 Studio & Automation Pack (5 tools)

Load with: twilio_explore category=studio

Tool Type Description
twilio_flow_create 🌊 Workflow Create a Twilio Studio flow from a JSON definition or natural language.
twilio_flow_list 📋 Workflow List all Studio flows in your account.
twilio_flow_execute ▶️ Workflow Trigger a Studio flow execution with parameters.
twilio_flow_diagram 🗺️ MCP App Visualize a Studio flow as a diagram.
twilio_webhook_wizard 🪄 Workflow Generate TwiML or webhook code for common scenarios (auto-reply, forward, etc.).

Use case: "Show me all my Studio flows" → auto-loads studio pack, uses twilio_flow_list.

📞 Contact Center Pack (5 tools)

Load with: twilio_explore category=contact-center

Tool Type Description
twilio_contact_center_setup 🏢 MCP App Set up a complete contact center: queues, workers, workflows, routing.
twilio_agent_status 👤 MCP App View agent availability, active tasks, real-time status dashboard.
twilio_queue_manager 📊 MCP App Manage call queues: see wait times, abandon rates, queue depth.
twilio_route_call 🔀 Workflow Route an incoming call to the best available agent based on skills/priority.
twilio_shift_schedule 📅 Workflow Set up agent shifts and availability schedules.

Use case: "Show me agent status" → auto-loads contact-center pack, uses twilio_agent_status.

💬 Conversations Pack (3 tools)

Load with: twilio_explore category=conversations

Tool Type Description
twilio_inbox 📬 MCP App Unified inbox view: all SMS, WhatsApp, chat messages in one dashboard.
twilio_conversation_create ➕ Workflow Create a multi-participant conversation (group chat).
twilio_omnichannel_send 📤 Workflow Send a message via any channel (SMS, WhatsApp, Messenger, etc.) from one tool.

Use case: "Show me my inbox" → auto-loads conversations pack, uses twilio_inbox.

📊 Analytics Pack (4 tools)

Load with: twilio_explore category=analytics

Tool Type Description
twilio_cost_report 💰 MCP App Cost breakdown by service, date range, with spending trends and alerts.
twilio_usage_alert 🔔 Workflow Set up alerts for usage thresholds (e.g., "Alert me when I hit $100 this month").
twilio_health_check 🩺 MCP App System health dashboard: error rates, delivery rates, uptime.
twilio_error_log 🚨 MCP App Visual log of recent errors with filters, sparklines, and suggested fixes.

Use case: "How much have I spent on SMS this month?" → auto-loads analytics pack, uses twilio_cost_report.

⚙️ Serverless Pack (3 tools)

Load with: twilio_explore category=serverless

Tool Type Description
twilio_deploy_function 🚀 Workflow Deploy a Twilio Function (serverless code) from source.
twilio_deploy_status 📊 Workflow Check deployment status and logs.
twilio_env_vars 🔧 Workflow Manage environment variables for your Twilio Functions.

Use case: "Deploy this function to handle incoming SMS" → auto-loads serverless pack, uses twilio_deploy_function.

🛡️ Compliance Pack (2 tools)

Load with: twilio_explore category=compliance

Tool Type Description
twilio_compliance_check ✅ MCP App Check your account's A2P 10DLC compliance status and required registrations.
twilio_register_brand 📝 Workflow Register your brand for A2P 10DLC messaging (US SMS compliance).

Use case: "Am I compliant for A2P messaging?" → auto-loads compliance pack, uses twilio_compliance_check.

🧠 Lazy Loading: Only Load What You Need

The problem with the official Twilio MCP: It loads 400+ tools on startup, polluting your AI's context window and slowing down every response.

Our solution: Lazy loading with intent detection.

How It Works

  1. Tier 1 (Always Loaded): 5 essential tools load instantly — twilio_explore, twilio_dashboard, twilio_quick_send, twilio_quick_call, twilio_lookup. These cover 80% of quick tasks.

  2. Tier 2 (Lazy Loaded): 11 specialized packs (50+ tools) sit dormant until needed. They load automatically when:

    • You explicitly call twilio_explore category=messaging
    • Your AI detects intent via keywords (e.g., you say "SMS campaign" → messaging pack auto-loads)
    • A Tier 1 tool suggests loading a pack (e.g., dashboard suggests exploring voice tools)

  3. Auto-Detection: The lazy loader scans your queries for keywords:

    • "Send a bulk SMS" → messaging pack loads
    • "Build an IVR" → voice pack loads
    • "Check if this number is fraud" → intelligence pack loads

  4. MCP Notifications: When a pack loads, we send tools/list_changed notifications so Claude instantly sees the new tools.

Example Flow

User: "I want to send an SMS campaign to 100 customers"
AI: [Detects keyword "SMS campaign" → auto-loads messaging pack]
AI: "The messaging pack is now loaded. I can use twilio_campaign_launch to send your campaign..."

Result: Your context window stays lean, tools appear exactly when needed, zero manual configuration.

🎨 MCP Apps: Visual Dashboards in HTML

17 tools in this MCP are MCP Apps — they return rich HTML dashboards using the structuredContent MCP spec.

What You Get

  • 📊 Data tables with sorting, status badges, sparklines
  • 📈 Charts & metrics — spending trends, call volume, error rates
  • 💬 Chat UIs — view SMS threads as beautiful conversation bubbles
  • 🌳 Flow diagrams — visualize IVRs and Studio flows
  • 🎛️ Dashboards — balance, usage, agent status, health checks

Example: twilio_dashboard

Returns an HTML dashboard with:

  • Account balance and phone number count
  • Recent message activity (sent/received/failed)
  • Recent call activity (completed/no-answer/failed)
  • Phone number inventory table with capabilities (SMS/Voice/MMS)

All MCP Apps

  1. twilio_dashboard — Account overview
  2. twilio_campaign_launch — Bulk message sender with progress
  3. twilio_conversation_thread — SMS conversation viewer
  4. twilio_message_log — Message history with filters
  5. twilio_build_ivr — IVR builder UI
  6. twilio_voicemail_box — Voicemail setup wizard
  7. twilio_call_analytics — Call volume dashboard
  8. twilio_deep_scan — Phone number intelligence report
  9. twilio_auth_flow_setup — 2FA flow configurator
  10. twilio_number_hunt — Number search results
  11. twilio_number_inventory — Phone number inventory
  12. twilio_flow_diagram — Studio flow visualizer
  13. twilio_contact_center_setup — Contact center builder
  14. twilio_agent_status — Agent availability dashboard
  15. twilio_queue_manager — Queue metrics
  16. twilio_inbox — Unified message inbox
  17. twilio_cost_report — Spending dashboard
  18. twilio_health_check — System health monitor
  19. twilio_error_log — Error log with filters
  20. twilio_compliance_check — Compliance status

🚦 Tool Safety Tiers

Every tool is annotated with a safety tier and MCP annotations (readOnlyHint, destructiveHint, costHint) so Claude knows what's safe to run autonomously.

🟢 Green Tier: Run Freely

Read-only, no side effects, no cost.

Examples:

  • twilio_explore — List available packs
  • twilio_dashboard — View account stats
  • twilio_lookup (basic) — Validate a phone number (free)
  • twilio_message_log — View message history

Claude can run these without asking. They're informational.

🟡 Yellow Tier: Proceed with Note

Writes data, sends messages, may cost small amounts (~$0.01).

Examples:

  • twilio_quick_send — Send an SMS (~$0.0079)
  • twilio_quick_call — Place a call (~$0.014/min)
  • twilio_otp_send — Send a 2FA code
  • twilio_auto_responder — Set up auto-replies

Claude will notify you: "I'm about to send an SMS which will cost ~$0.01. Proceed?"

🔴 Red Tier: Requires Confirmation

Destructive, expensive, or irreversible.

Examples:

  • twilio_number_provision — Buy a phone number (~$1-$2/month)
  • twilio_number_release — Delete a phone number (destructive)
  • twilio_campaign_launch — Send 1000s of messages ($$)
  • twilio_call_blast — Place simultaneous calls ($$)

Claude will always ask: "This tool will purchase a phone number for ~$1/month. Confirm?"

MCP Annotations

We use the official MCP annotations spec:

{
  readOnlyHint: true,        // Green: safe to run autonomously
  destructiveHint: true,     // Red: requires confirmation
  idempotentHint: true,      // Safe to retry
  costHint: true,            // Costs money
  estimatedCost: "~$0.01"    // Human-readable cost
}

Claude respects these and adjusts its behavior accordingly.

⚙️ Configuration

Environment Variables

The recommended way to authenticate:

export TWILIO_ACCOUNT_SID="ACxxxxx"
export TWILIO_API_KEY="SKxxxxx"
export TWILIO_API_SECRET="your_secret"

CLI Arguments

Alternatively, pass credentials as a CLI argument:

twilio-mcp "ACxxxxx:SKxxxxx:your_secret"

Format: account_sid:api_key:api_secret

Claude Desktop Config

Full example:

{
  "mcpServers": {
    "twilio": {
      "command": "npx",
      "args": ["-y", "@busybee/twilio-mcp"],
      "env": {
        "TWILIO_ACCOUNT_SID": "ACxxxxx",
        "TWILIO_API_KEY": "SKxxxxx",
        "TWILIO_API_SECRET": "your_secret"
      }
    }
  }
}

Getting Credentials

  1. Account SID: Visible on your Twilio Console dashboard
  2. API Key/Secret: Create an API Key here

Why API Keys? They're more secure than using your auth token. You can rotate them, revoke them, and scope their permissions.

🛠️ Development

Build from source

git clone https://github.com/yourusername/twilio-mcp.git
cd twilio-mcp
npm install
npm run build
npm link  # Use locally

Run in dev mode

npm run dev  # Watch mode
npm start    # Run the built server

Testing

npm test

📖 Examples

Send a quick SMS

User: "Send an SMS to +15551234567 saying 'Meeting at 3pm'"

→ twilio_quick_send auto-selects a sender, validates the number, sends.

Launch a campaign

User: "Send 'Sale ends tonight!' to these 500 customers"

→ Loads messaging pack, uses twilio_campaign_launch, shows progress dashboard.

Build an IVR

User: "Build an IVR: press 1 for sales, 2 for support, 3 for billing"

→ Loads voice pack, uses twilio_build_ivr, generates TwiML and webhook code.

Check for fraud

User: "Is +15559876543 safe to call?"

→ Loads intelligence pack, uses twilio_fraud_check, returns fraud score and sim swap risk.

View account dashboard

User: "Show me my Twilio dashboard"

→ twilio_dashboard returns rich HTML: balance, usage, active numbers, recent activity.

🤝 Contributing

We welcome contributions! If you want to add a tool, improve a pack, or fix a bug:

  1. Fork the repo
  2. Create a feature branch (git checkout -b feature/cool-tool)
  3. Add your tool to the appropriate pack (extend BasePack)
  4. Add keywords to PACK_KEYWORDS in lazy-loader.ts
  5. Update this README with your new tool
  6. Submit a PR

Adding a New Tool

  1. Extend the appropriate pack class (e.g., MessagingPack)
  2. Use registerTool() helper:
this.registerTool({
  name: 'twilio_my_tool',
  description: 'Does something awesome',
  category: 'messaging',
  safety: 'yellow',
  tier: 2,
  annotations: { costHint: true, estimatedCost: '~$0.01' },
  inputSchema: z.object({
    param: z.string().describe('A parameter'),
  }),
  handler: async (params) => {
    // Your logic here
    return this.textResult('Success!');
  },
});
  1. Add keywords to PACK_KEYWORDS for auto-detection.

📜 License

MIT License — see LICENSE file.

Built with ❤️ by the BusyBee team.

Twilio® is a registered trademark of Twilio Inc. This project is not affiliated with, endorsed by, or sponsored by Twilio Inc.

🐝 About BusyBee

We build tools that don't suck. MCP servers, AI workflows, and infrastructure that just works.

More projects:

Follow us: @busybee_tools

🚀 Get Started Now

npx @busybee/twilio-mcp

Then add it to your Claude Desktop config and say: "Show me my Twilio dashboard"

Welcome to Twilio MCP that doesn't suck. 🎉