clawdbot-workspace/twilio-mcp/README.md

# @busybee/twilio-mcp

**The Twilio MCP that doesn't suck.**

[![npm version](https://img.shields.io/npm/v/@busybee/twilio-mcp.svg)](https://www.npmjs.com/package/@busybee/twilio-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP Protocol](https://img.shields.io/badge/MCP-1.0-blue.svg)](https://modelcontextprotocol.io)

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)

```bash
npx @busybee/twilio-mcp
```

Or install globally:

```bash
npm install -g @busybee/twilio-mcp
```

### 2. Configure Claude Desktop

Add to your `claude_desktop_config.json`:

```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](https://console.twilio.com) (visible on dashboard)
- **API Key/Secret**: [Create an API Key](https://console.twilio.com/account/keys-credentials/api-keys) (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

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:

```typescript
{
  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:

```bash
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:

```bash
twilio-mcp "ACxxxxx:SKxxxxx:your_secret"
```

Format: `account_sid:api_key:api_secret`

### Claude Desktop Config

Full example:

```json
{
  "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](https://console.twilio.com)
2. **API Key/Secret:** [Create an API Key here](https://console.twilio.com/account/keys-credentials/api-keys)

**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

```bash
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

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

### Testing

```bash
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:

```typescript
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!');
  },
});
```

3. Add keywords to `PACK_KEYWORDS` for auto-detection.

---

## 📜 License

MIT License — see [LICENSE](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](https://github.com/busybee/postgres-mcp) — PostgreSQL MCP that doesn't dump your entire schema
- [@busybee/github-mcp](https://github.com/busybee/github-mcp) — GitHub MCP with PR workflows, not raw REST endpoints
- [@busybee/stripe-mcp](https://github.com/busybee/stripe-mcp) — Stripe MCP that understands subscriptions and payments

**Follow us:** [@busybee_tools](https://twitter.com/busybee_tools)

---

## 🚀 Get Started Now

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