Skip to main content
Glama
sebastienfi

mcp-twilio-sms

by sebastienfi
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

MCP Twilio SMS

MCP server that lets Claude send SMS text messages via Twilio. 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.

Related MCP server: twilio-mcp

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 — install with curl -LsSf https://astral.sh/uv/install.sh | sh

  • Python ≥ 3.11 (uv will fetch it if missing)

  • A Twilio account

2. Get Twilio credentials

From the Twilio Console:

  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

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:

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

# 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):

{
  "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:

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 inline metadata, so it runs standalone without uv sync:

uv run --script server.py

Development

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

No test suite or linter is configured.

License

MIT

Available Tools

2 tools
get_sms_statusA

Check the delivery status of a sent SMS.

USAGE:

  • Call after send_sms() to verify delivery

  • Delivery confirmation may take a few seconds

STATUS VALUES:

  • queued: Message is queued for sending

  • sending: Message is being sent

  • sent: Message was sent to carrier

  • delivered: Carrier confirmed delivery to recipient

  • failed: Message could not be sent

  • undelivered: Carrier could not deliver the message

Args: message_sid: The message SID returned by send_sms (e.g. "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")

ParametersJSON Schema
NameRequiredDescriptionDefault
message_sidYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does well: it discloses the asynchronous nature of delivery confirmation and enumerates all six status values with their meanings. It omits permission/auth requirements and whether polling is expected, which are the remaining gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded purpose followed by labeled USAGE, STATUS VALUES, and Args sections. The status enumeration is bulky but every entry earns its place by defining an ambiguous term the agent will encounter.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return-shape detail isn't required, and the description still explains the status vocabulary an agent needs to interpret it. Usage sequencing and the single parameter's format are covered, leaving nothing essential missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate; it names the parameter (message_sid), states its origin (returned by send_sms), and gives a format example ('SMxxxxxxxx...'). That materially exceeds the bare string schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource: 'Check the delivery status of a sent SMS.' This clearly distinguishes it from its only sibling send_sms, which sends rather than queries.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says to call it after send_sms() to verify delivery and warns that confirmation may take a few seconds, giving the agent a sequencing condition. No when-not guidance, but the tool's scope is narrow enough that this is minor.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

send_smsA

Send an SMS text message via Twilio.

WORKFLOW:

  1. Call send_sms(to="+33612345678", body="Your message here")

  2. Get back a message_sid and status

  3. Optionally call get_sms_status(message_sid=...) later to confirm delivery

PARAMETERS:

  • to: Recipient phone number in E.164 format ("+33612345678" for France, "+15551234567" for US). Must include country code with + prefix.

  • body: The text message content. Max 1600 characters (messages over 160 characters are split into segments and billed per segment).

  • from_number: Override the sender phone number. Default: TWILIO_PHONE_NUMBER env var. Must be a Twilio number you own.

RETURNS:

  • message_sid: Unique identifier for tracking this message

  • status: Initial status (typically "queued")

  • to/from: The phone numbers used

  • segments: Number of message segments (billing units)

TIPS:

  • Keep messages under 160 characters for 1 segment (cheapest)

  • Unicode characters (accents, emojis) reduce the limit to 70 chars/segment

  • Use get_sms_status() to verify delivery if needed

Args: to: Recipient phone number in E.164 format (e.g. "+33612345678") body: The text message content (max 1600 characters) from_number: Sender phone number override (default: TWILIO_PHONE_NUMBER env var)

ParametersJSON Schema
NameRequiredDescriptionDefault
toYes
bodyYes
from_numberNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does well: it discloses segment-based billing, the 160/70-character segment boundaries, the unicode penalty, and the default sender resolution via the TWILIO_PHONE_NUMBER env var. It does not mention auth/credential requirements, rate limits, or that a sent SMS cannot be recalled, so it falls short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the purpose, then cleanly sectioned into WORKFLOW/PARAMETERS/RETURNS/TIPS, which is easy to scan. The trailing 'Args:' block restates the three parameters almost verbatim, adding length without new information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists and the description still summarizes the return fields (message_sid, status, to/from, segments) in a way that tells the agent what to pass to get_sms_status. Format, limits, defaults, and the follow-up workflow are all covered; nothing needed to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and every parameter is fully compensated: 'to' specifies E.164 with country-code and example formats, 'body' gives the 1600-char max and segment splitting behavior, and 'from_number' states the default and the Twilio-number ownership constraint.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Send an SMS text message via Twilio') and the resource is unambiguous against the only sibling, get_sms_status, which reads status rather than sending.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides an explicit numbered workflow showing this is the entry point, then routes to the alternative ('Optionally call get_sms_status(message_sid=...) later to confirm delivery') with the condition that selects it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedget_sms_status
    • First observedsend_sms
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.6/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: send_sms sends a message, get_sms_status checks delivery status. There is no overlap or ambiguity; the workflow explicitly links them.

Naming Consistency5/5

Both tools use a consistent verb_noun snake_case pattern (send_sms, get_sms_status). The naming is predictable and easy to understand.

Tool Count4/5

Two tools cover the core send-and-verify workflow, which is focused and appropriate for a minimal SMS server. It is slightly under the typical 3-15 range but each tool earns its place without redundancy.

Completeness4/5

The surface covers sending an SMS and checking its status, which are the essential operations. Minor gaps exist (e.g., listing sent messages or retrieving full message details), but agents can work around them for the stated purpose.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • smsmanager

    larsdittinger
    F
    license
    A
    quality
    D
    maintenance
    MCP server for sending SMS messages via SmsManager.cz HTTP API, supporting high, economy, and low delivery gateways.
    1
    -