# twilio-mcp

Dedalus MCP server for Twilio communications. It exposes SMS/MMS sending, message listing, message lookup, outbound calls, incoming phone number listing, and phone number lookup.

## Tools

- `send_sms` - Send an SMS or MMS.
- `list_messages` - List account messages with optional filters.
- `get_message` - Fetch one message by Message SID.
- `make_call` - Start an outbound voice call.
- `list_phone_numbers` - List incoming phone numbers on the account.
- `lookup_phone_number` - Lookup a phone number with Twilio Lookup v2.

## Safety Notes

Twilio write tools can cost money and contact real users.

- `send_sms` sends a real SMS/MMS and may incur messaging charges.
- `make_call` starts a real phone call and may incur voice charges.
- `lookup_phone_number` may incur Lookup charges depending on requested fields.

Confirm phone numbers, message bodies, call URLs, and user intent before using write tools. Do not run `src/_client.py` against production phone numbers unless you intentionally want to send a test SMS and place a test call.

Never commit Twilio Account SIDs with auth tokens, message bodies, phone number lists, call logs, or Lookup results containing personal data.

## Authentication

Twilio REST uses HTTP Basic auth where username is `TWILIO_ACCOUNT_SID` and password is `TWILIO_AUTH_TOKEN`. Current `dedalus_mcp.Connection` accepts one secret value for header injection, so this server uses:

```text
Authorization: Basic <base64(TWILIO_ACCOUNT_SID:TWILIO_AUTH_TOKEN)>
```

Connection details:

- Connection names: `twilio_rest` for `api.twilio.com` and `twilio_lookup` for `lookups.twilio.com`
- Secret key: `TWILIO_BASIC_AUTH`
- Header format: `Basic {api_key}`
- Base URLs: `https://api.twilio.com`, `https://lookups.twilio.com`

Required variables:

```bash
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_BASIC_AUTH=<base64 of ACCOUNT_SID:AUTH_TOKEN>
DEDALUS_AS_URL=https://as.dedaluslabs.ai
```

For local convenience, `src/twilio_tools.py` and `src/_client.py` can derive `TWILIO_BASIC_AUTH` when both `TWILIO_ACCOUNT_SID` and `TWILIO_AUTH_TOKEN` are present. Prefer storing only `TWILIO_BASIC_AUTH` as the DAuth credential in production.

## Run Locally

```bash
uv run python src/main.py
```

In another terminal:

```bash
MCP_SERVER_URL=http://127.0.0.1:8080/mcp uv run python src/_client.py
```

Set `TWILIO_TEST_FROM`, `TWILIO_TEST_TO`, `TWILIO_TEST_MESSAGE_SID`, and `TWILIO_TEST_CALL_URL` to safe test resources. The client intentionally calls paid/user-contacting tools.

## Deploy

Publish as `dedalus-labs/twilio-mcp`, configure `TWILIO_BASIC_AUTH` as a required DAuth credential and `TWILIO_ACCOUNT_SID` as an environment variable or required config, deploy, then run:

```bash
DEDALUS_MCP_SERVER_ONLY=1 DEDALUS_MCP_SERVER=dedalus-labs/twilio-mcp uv run python src/_client.py
```