twilio-messaging

This MCP server acts as an interface to Twilio's Messaging API, enabling you to send SMS messages and handle status callbacks within the Model Context Protocol (MCP) framework. The server exposes a tool named send-sms that validates server readiness before sending a message, and it provides a resources endpoint for retrieving the latest status callback data via the twilio://statuscallback resource with enhanced error handling. You can integrate it with Claude AI or other MCP-enabled agents to compose, dispatch, and monitor SMS messages. To run, use npm/npx as described in the installation section, passing your Twilio credentials and the recipient number as arguments. Environment variables for ngrok (NGROK_AUTH_TOKEN and optional NGROK_CUSTOM_DOMAIN) enable proper callback handling.

Prerequisites:

• Node.js v18.0.0 or newer
• npm (comes with Node)
• A Twilio account with Account SID, API Key and Secret, and a Twilio phone number
• (Optional) ngrok account with an auth token and optional custom domain

Install the MCP server package:

npm install @deshartman/twilio-messaging-mcp-server

Or run directly with npx (no installation required):

# Run with required parameters (accountSid, apiKey, apiSecret, number) using npx
npx @deshartman/twilio-messaging-mcp-server <accountSid> <apiKey> <apiSecret> <number>

If you prefer to supply credentials via environment variables and run with Node.js directly:

# Example with Node.js (after building if needed by the package)
env ACCOUNT_SID=YOUR_ACCOUNT_SID API_KEY=YOUR_API_KEY API_SECRET=YOUR_API_SECRET TWILIO_NUMBER=YOUR_TWILIO_NUMBER \
NGROK_AUTH_TOKEN=YOUR_NGROK_TOKEN NGROK_CUSTOM_DOMAIN=your-domain.ngrok.dev node build/index.js <accountSid> <apiKey> <apiSecret> <number>

Tips:

• The server supports sending SMS and retrieving last raw status callback data via the twilio://statuscallback resource with enhanced error handling.
• When using ngrok for public callbacks, ensure NGROK_AUTH_TOKEN is set; NGROK_CUSTOM_DOMAIN is optional but can help with stable callbacks.
• If you encounter tunnel or ENOTEMPTY npm errors, try running the server directly with Node.js or reattempt with a different ngrok domain. The MCP integration is designed to work with the npx-executable package for quick start.
• The MCP tool name exposed is send-sms, used to dispatch an SMS through Twilio after validating server readiness.
• The npm package name for reference is @deshartman/twilio-messaging-mcp-server; use it in your MCP configurations or for local development.