# MCP Twilio SMS

MCP server that lets Claude send SMS text messages via [Twilio](https://www.twilio.com/). Single-file Python server (`server.py`) exposing two MCP tools: `send_sms` and `get_sms_status`.

## How It Works

```
Claude → send_sms(to, body)              → Twilio API → SMS delivered
Claude → get_sms_status(message_sid)     → Twilio API → delivery status
```

The server speaks MCP over stdio. Claude (Code or Desktop) launches it as a subprocess, Twilio credentials are supplied via environment variables, and the two tools wrap the official `twilio` Python SDK.

## Tools

### `send_sms`

Send a text message. Parameters:
- `to` — Recipient phone number in E.164 format (e.g. `+33612345678`)
- `body` — Message text (max 1600 characters)
- `from_number` — Optional sender override (default: `TWILIO_PHONE_NUMBER` env var)

Returns `message_sid`, `status`, `to`, `from`, and `segments`.

### `get_sms_status`

Check delivery status of a sent message by its `message_sid`. Returns one of: `queued`, `sending`, `sent`, `delivered`, `failed`, or `undelivered` (plus `error_code`/`error_message` on failure).

## Setup

### 1. Prerequisites

- [uv](https://docs.astral.sh/uv/) — install with `curl -LsSf https://astral.sh/uv/install.sh | sh`
- Python ≥ 3.11 (uv will fetch it if missing)
- A [Twilio](https://www.twilio.com/) account

### 2. Get Twilio credentials

From the [Twilio Console](https://console.twilio.com/):

1. Copy your **Account SID** and **Auth Token** from the dashboard.
2. Get an SMS-capable phone number (Console → Phone Numbers → **Buy a number**, or use the trial number). It must be in E.164 format, e.g. `+1234567890`.

> **Trial accounts** can only send SMS to phone numbers you have verified in the Console (Verified Caller IDs), and messages are prefixed with a trial notice. Upgrade the account to remove both limits.

### 3. Install dependencies

```bash
git clone git@github.com:sebastienfi/mcp-twilio-sms.git
cd mcp-twilio-sms
uv sync
```

### 4. Configure secrets

Create a secrets file (shared with other MCP servers) and lock it down:

```bash
mkdir -p ~/.config/mcp
cat > ~/.config/mcp/secrets.env <<'EOF'
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your-auth-token
TWILIO_PHONE_NUMBER=+1234567890
EOF
chmod 600 ~/.config/mcp/secrets.env
```

See `.env.example` for the full list of variables.

### 5. Verify it runs

```bash
# Load secrets and start the server (Ctrl-C to stop — it waits for a client on stdio)
set -a; source ~/.config/mcp/secrets.env; set +a
uv run python server.py
```

The server has no console UI; it waits for an MCP client on stdio. Register it with Claude (below) to actually use it.

### 6. Register with Claude Code

Add to `~/.claude.json` under `mcpServers` (use absolute paths):

```json
{
  "twilio-sms": {
    "command": "/bin/bash",
    "args": [
      "-c",
      "set -a; source /Users/you/.config/mcp/secrets.env; set +a; exec /opt/homebrew/bin/uv run --directory /path/to/mcp-twilio-sms python server.py"
    ]
  }
}
```

Or with the CLI:

```bash
claude mcp add twilio-sms -- /bin/bash -c \
  "set -a; source ~/.config/mcp/secrets.env; set +a; exec uv run --directory $(pwd) python server.py"
```

Restart Claude Code, then confirm with `/mcp` that `twilio-sms` is connected.

### 7. Register with Claude Desktop

Add the same block to `claude_desktop_config.json`:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

Use absolute paths for both `uv` and the project directory, then restart Claude Desktop.

## Running directly

`server.py` carries [PEP 723](https://peps.python.org/pep-0723/) inline metadata, so it runs standalone without `uv sync`:

```bash
uv run --script server.py
```

## Development

```bash
uv sync                   # Install dependencies
uv run python server.py   # Run the MCP server (stdio transport)
```

No test suite or linter is configured.

## License

[MIT](LICENSE)