# Twilio MCP Server

MCP (Model Context Protocol) server for Twilio. Uses **Account SID**, **Auth Token**, and your **Twilio phone number** from environment variables. Lets AI assistants (e.g. Cursor) send SMS, list numbers, and read account info via tools.

**Configured:** Account SID, Auth Token, and phone number **+14632175613** are set in `twilio-mcp-server/.env` (do not commit).  
**LiveKit:** To route phone calls to the LiveKit voice agent, see [Twilio + LiveKit telephony setup](../docs/TWILIO-LIVEKIT-TELEPHONY.md).

## Credentials

Set these in environment or in a `.env` file:

| Variable | Required | Description |
|----------|----------|-------------|
| `TWILIO_ACCOUNT_SID` | Yes | Account SID (starts with `AC`) from [Twilio Console](https://console.twilio.com/) |
| `TWILIO_AUTH_TOKEN` | Yes | Auth Token (primary account secret) |
| `TWILIO_PHONE_NUMBER` | Recommended | Your Twilio number in E.164 (e.g. `+15551234567`). Used as default "from" for `send_sms`. |

## Setup

1. Copy env example and fill in your values:

   ```bash
   cp .env.example .env
   # Edit .env with your Account SID, Auth Token, and phone number
   ```

2. Install dependencies (if not already done):

   ```bash
   npm install
   ```

3. Run the server (stdio):

   ```bash
   npm start
   ```

## Cursor MCP configuration

To use this server in Cursor:

1. **Option A – Project config (this repo)**  
   This project already has `.cursor/mcp.json` that starts the Twilio MCP server. Set your credentials via either:

   - A **`.env`** file in the project root or in `twilio-mcp-server/` with `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN`, and `TWILIO_PHONE_NUMBER` (do not commit `.env`), or  
   - **Environment variables** in your shell / Cursor, or  
   - An **`env`** block inside the `twilio` entry in `.cursor/mcp.json` (do not commit real secrets; use env vars or `.env` instead).

2. **Option B – User config**  
   Add the same `twilio` entry to your user MCP config:

   - **Linux**: `~/.config/cursor/mcp.json` or `~/.cursor/mcp.json`
   - **macOS**: `~/.cursor/mcp.json`
   - **Windows**: `%APPDATA%\Cursor\mcp.json`

   Ensure Cursor is started from the project root so `node twilio-mcp-server/index.js` resolves, or use the full path to `index.js`.

3. Restart Cursor after changing MCP config.

## Tools

| Tool | Description |
|------|-------------|
| `send_sms` | Send an SMS to a number. Uses `TWILIO_PHONE_NUMBER` as default "from" unless `from` is provided. |
| `get_account_info` | Return Twilio account info (friendly name, status, type). |
| `list_phone_numbers` | List Twilio phone numbers on the account. |
| `get_configured_phone_number` | Return the value of `TWILIO_PHONE_NUMBER` from env. |

## Security

- Do not commit `.env` or real credentials in `.cursor/mcp.json`.
- Prefer environment variables or a local `.env` that is gitignored.