mcp-twilio-sms: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MCP server that lets Claude send SMS text messages via Twilio. Single-file Python server (server.py) exposing two MCP tools: send_sms (sends a message) and get_sms_status (checks delivery).

Commands

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

# Or run directly (PEP 723 inline metadata):
uv run --script server.py

No test suite or linter is configured.

MCP Server Registration

This server is registered in both Claude Code and Claude Desktop via a bash wrapper that sources secrets from a centralized env file:

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

• Secrets file: ~/.config/mcp/secrets.env (chmod 600) — shared with other MCP servers
• Required secrets: TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_PHONE_NUMBER

Architecture

Single-file design — all logic lives in server.py:

• MCP layer: Uses mcp[cli] / FastMCP to expose tools over stdio
• Twilio integration: Uses the official twilio Python SDK to send messages and check status
• Two tools: send_sms (create + send message) and get_sms_status (fetch delivery status by SID)

Environment Variables

Required: TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_PHONE_NUMBER. See .env.example.