Jake Shore ddfa0956fe Daily backup: 2026-02-03 — 4 new MCP servers, multi-panel threads, LocalBosses bug fixes

2026-02-03 23:01:52 -05:00

22 KiB

Raw Blame History

@busybee/twilio-mcp

The Twilio MCP that doesn't suck.

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:

Account SID: Twilio Console (visible on dashboard)
API Key/Secret: Create an API Key (recommended for security)

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

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

twilio_dashboard — Account overview
twilio_campaign_launch — Bulk message sender with progress
twilio_conversation_thread — SMS conversation viewer
twilio_message_log — Message history with filters
twilio_build_ivr — IVR builder UI
twilio_voicemail_box — Voicemail setup wizard
twilio_call_analytics — Call volume dashboard
twilio_deep_scan — Phone number intelligence report
twilio_auth_flow_setup — 2FA flow configurator
twilio_number_hunt — Number search results
twilio_number_inventory — Phone number inventory
twilio_flow_diagram — Studio flow visualizer
twilio_contact_center_setup — Contact center builder
twilio_agent_status — Agent availability dashboard
twilio_queue_manager — Queue metrics
twilio_inbox — Unified message inbox
twilio_cost_report — Spending dashboard
twilio_health_check — System health monitor
twilio_error_log — Error log with filters
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

Account SID: Visible on your Twilio Console dashboard
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:

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

Adding a New Tool

Extend the appropriate pack class (e.g., MessagingPack)
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!');
  },
});

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:

@busybee/postgres-mcp — PostgreSQL MCP that doesn't dump your entire schema
@busybee/github-mcp — GitHub MCP with PR workflows, not raw REST endpoints
@busybee/stripe-mcp — Stripe MCP that understands subscriptions and payments

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. 🎉

22 KiB Raw Blame History Unescape Escape

@busybee/twilio-mcp

🔥 Why This Exists

🆚 How We Stack Up

🚀 Quick Start

1. Install via npx (no installation needed)

2. Configure Claude Desktop

3. Restart Claude and go

📦 Tool Catalog

🟢 Tier 1 — Always Loaded (5 tools)

📱 Messaging Pack (6 tools)

📞 Voice Pack (7 tools)

🔍 Number Intelligence Pack (4 tools)

🔐 Verify & Security Pack (4 tools)

📞 Phone Numbers Pack (5 tools)

🎨 Studio & Automation Pack (5 tools)

📞 Contact Center Pack (5 tools)

💬 Conversations Pack (3 tools)

📊 Analytics Pack (4 tools)

⚙️ Serverless Pack (3 tools)

🛡️ Compliance Pack (2 tools)

🧠 Lazy Loading: Only Load What You Need

How It Works

Example Flow

🎨 MCP Apps: Visual Dashboards in HTML

What You Get

Example: twilio_dashboard

All MCP Apps

🚦 Tool Safety Tiers

🟢 Green Tier: Run Freely

🟡 Yellow Tier: Proceed with Note

🔴 Red Tier: Requires Confirmation

MCP Annotations

⚙️ Configuration

Environment Variables

CLI Arguments

Claude Desktop Config

Getting Credentials

🛠️ Development

Build from source

Run in dev mode

Testing

📖 Examples

Send a quick SMS

Launch a campaign

Build an IVR

Check for fraud

View account dashboard

🤝 Contributing

Adding a New Tool

📜 License

🐝 About BusyBee

🚀 Get Started Now

22 KiB

Raw Blame History

Example: `twilio_dashboard`