Unified Communication Gateway for Twilio Messaging via MCP

An implementation of an MCP server engineered for dispatching short message service (SMS) communications utilizing the Twilio Application Programming Interface (API).

Core Capabilities

• Initiate and dispatch SMS transmissions using the Twilio infrastructure.
• Process and manage incoming delivery status notifications from Twilio, featuring advanced reception and processing through the @deshartman/mcp-status-callback utility.
• Designed for interoperability with AI reasoning engines, notably Claude, via the Model Context Protocol (MCP).
• Deployment simplicity assured through direct execution via the npx utility, circumventing traditional installation procedures.

Prerequisites for Operation

• A functioning Node.js environment, version 18.0.0 or newer.
• A valid Twilio subscriber account provisioning the following credentials:
  • Account Identifier (SID)
  • Authentication Key and associated Secret
  • An active, provisioned Twilio telephone number.
• An active account registered with ngrok, possessing:
  • An authorization token.
  • (Optional) A user-defined public domain name for tunneling.

Setup Procedure

Installation via npm package manager:

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

Alternatively, for immediate execution without persistent installation:

npx @deshartman/twilio-messaging-mcp-server <accountSid> <apiKey> <apiSecret> <number>

Execution Via NPX

The package is engineered for direct execution using npx, capitalizing on the bin field configuration in its manifest file:

# Standard execution with necessary input parameters
npx @deshartman/twilio-messaging-mcp-server <accountSid> <apiKey> <apiSecret> <number>

# Execution incorporating environment variables for ngrok configuration
env NGROK_AUTH_TOKEN=your_token NGROK_CUSTOM_DOMAIN=your_domain.ngrok.dev npx @deshartman/twilio-messaging-mcp-server <accountSid> <apiKey> <apiSecret> <number>

Configuration Directives (Environment Variables)

• NGROK_AUTH_TOKEN: The necessary authentication credential for the ngrok service (mandatory for reliable webhook callback capture).
• NGROK_CUSTOM_DOMAIN: An optional, user-specified public endpoint for the ngrok tunnel.

Operational Instructions

Initiating the Server Service

Server launch can be managed using the included execution script, preferably by defining sensitive data within a .env configuration file (refer to .env.example for structure):

# Establish the .env file with secret configuration details

# Execute the service launch routine (arguments are inferred from the environment)
./run-server.sh

The recommended .env structure for comprehensive configuration:

ACCOUNT_SID=YOUR_ACCOUNT_SID
API_KEY=YOUR_API_KEY
API_SECRET=YOUR_API_SECRET
TWILIO_NUMBER=YOUR_TWILIO_PHONE_NUMBER
NGROK_AUTH_TOKEN=YOUR_NGROK_AUTH_TOKEN
NGROK_CUSTOM_DOMAIN=your-domain.ngrok.dev

This .env methodology enhances credential secrecy by avoiding command history exposure and streamlines the invocation workflow.

Direct Execution with Node Runtime

env NGROK_AUTH_TOKEN=your_ngrok_auth_token NGROK_CUSTOM_DOMAIN=your_domain.ngrok.dev node build/index.js <accountSid> <apiKey> <apiSecret> <number>

MCP Framework Integration Points

This server component exposes the following interfaces for the Model Context Protocol:

Service Endpoints (Tools)

• send-sms: A utility function to dispatch an SMS via Twilio, incorporating pre-flight server operational validation.

Data Accessors (Resources)

• twilio://statuscallback: Provides retrieval of the most recently documented, raw status notification payload received from Twilio, complete with integrated error diagnostics.

Abstract Operations (Prompts)

• SendSMS: A standardized prompt structure tailored for initiating an SMS transmission through the Twilio Messaging MCP Server interface.

Diagnostic Guidance

Issues Related to ngrok Tunnel Establishment

If an error resembling the following is encountered:

failed to start tunnel: The endpoint 'https://your-domain.ngrok.dev' is already online.

Mitigation strategies include:

1. Terminating the pre-existing active tunnel session.
2. Assigning a distinct public domain name for the new connection.
3. Initiating both concurrent endpoints with the --pooling-enabled directive to distribute load.

Filesystem Conflict Error (ENOTEMPTY)

Should an npm error manifest as:

npm ERR! code ENOTEMPTY
npm ERR! syscall rename

It is advised to switch the execution method, attempting direct launch via the Node.js runtime instead of relying on npx.

Software Governance

Licensed under the MIT Agreement.