TW
OfficialCommunicationAPI Integration

Twilio MCP Server: Send SMS, Manage Numbers

Send SMS, manage phone numbers, and configure your account with the Twilio MCP server for reliable messaging and streamlined number management.

View on GitHub
Quick Install
npx -y @twilio-labs/mcp

Overview

The Twilio MCP (Model Context Protocol) Server exposes Twilio APIs through an MCP-compatible server so AI assistants and other tools can request and use Twilio context and actions safely. It implements the MCP spec to make Twilio resources — messaging, phone number management, and account configuration — available as machine-readable tools for downstream model integrations and orchestration systems.

This project contains two primary server implementations: a Twilio-tailored MCP server that exposes Twilio’s public APIs, and a generic OpenAPI-backed MCP server that can host any OpenAPI v3 specification. For developers building AI integrations or automations, the Twilio MCP Server simplifies sending SMS, managing phone numbers, and limiting surface area exposed to models through filtering and configuration options.

Features

  • Exposes Twilio public APIs via MCP so AI tools can discover and call Twilio endpoints
  • OpenAPI-backed server to serve any OpenAPI v3 specification as MCP tools
  • Fine-grained filtering with –services and –tags to control which APIs are exposed
  • Simple CLI startup via npx or installable package
  • Supports Twilio API Key authentication (Account SID/API Key:API Secret)
  • Useful for prototyping integrations between LLM-based assistants and Twilio

Packages

PackagePurpose
@twilio-alpha/mcpMCP Server exposing Twilio public APIs
@twilio-alpha/openapi-mcp-serverGeneric MCP server that serves a provided OpenAPI v3 spec

Repository: https://github.com/twilio-labs/mcp

Installation / Configuration

Quick start (one-off via npx):

# Start the Twilio MCP server using npx
npx -y @twilio-alpha/mcp YOUR_ACCOUNT_SID/YOUR_API_KEY:YOUR_API_SECRET

Example using the OpenAPI MCP server with a local spec:

# Serve an OpenAPI v3 file as an MCP server
npx -y @twilio-alpha/openapi-mcp-server --apiPath ./openapi.yaml

Environment and credential notes:

  • Twilio credential format: ACCOUNT_SID/API_KEY:API_SECRET
  • Create API keys at: https://www.twilio.com/docs/iam/api-keys
  • You can also run the package after installing:
# Install locally
npm install -g @twilio-alpha/mcp

# Run with credentials
mcp YOUR_ACCOUNT_SID/YOUR_API_KEY:YOUR_API_SECRET

Configuration flags (common):

  • –services — comma-separated list of Twilio services to expose (e.g., messages,incoming_phone_numbers)
  • –tags — expose APIs filtered by OpenAPI tags
  • –apiPath — (openapi-mcp-server) path to OpenAPI v3 files or directory

    Example limiting surface area:

    npx -y @twilio-alpha/mcp YOUR_SID/YOUR_KEY:YOUR_SECRET --services messages,incoming_phone_numbers

    Available Resources

    • Twilio Public API endpoints (Messaging, Phone Numbers, Account configuration, etc.) exposed as MCP tools
    • OpenAPI v3 specs (served by openapi-mcp-server) — any tool represented in OpenAPI can become an MCP tool
    • Package README files:
      • packages/mcp/README.md — Twilio MCP package docs
      • packages/openapi-mcp-server/README.md — OpenAPI MCP server docs

    Use Cases

    • Send transactional SMS from an AI assistant
      • Configure the MCP server to expose only the Messages API, then allow your assistant to call the send message tool for notifications or verification flows.
    • Provision and manage phone numbers
      • Expose phone-number-related endpoints to let an automated workflow search for, purchase, or release numbers based on criteria supplied by an LLM-based operator.
    • Automated account configuration
      • Use MCP tools to programmatically update messaging services, webhook URLs, or number configurations as part of a larger automation pipeline.
    • Rapid prototyping with custom APIs
      • Wrap your own OpenAPI spec with openapi-mcp-server to expose domain-specific tools to models without writing a custom MCP adapter.

    Concrete example (start server, then restrict to messaging APIs):

    # Start server exposing only messaging and phone-number APIs
npx -y @twilio-alpha/mcp ACxxxxxxxxxx/Skxxxxxxxx:yourSecret --services messages,incoming_phone_numbers

    Then configure your MCP-aware assistant or tool to connect to the running MCP server. The assistant will discover and be able to call Twilio endpoints described by the exposed tools.

    Best Practices & Troubleshooting

    • Security: Do not run untrusted, community MCP servers alongside official ones. Limit exposed APIs with –services/–tags and only provide minimal credentials required for the tasks.
    • Context size: LLM integrations should filter and load only required APIs to avoid context limits; use tags/services to reduce payload.
    • Authentication errors: Verify the credential format (ACCOUNT_SID/API_KEY:API_SECRET) and ensure the API Key has required permissions.
    • API versioning: Confirm you’re using the appropriate Twilio API versions for specific endpoints.

    For development: run npm test, linting (npm run lint), and fix issues (npm run lint:fix) as documented in the repository.

    Contributions and issues: open a PR or issue on the GitHub repository linked above. The project is licensed under the ISC License.

    Tags:aiapi-integrationcommunicationmcpopenapiopenapi generatoropenapi-generatoropenapi3twilio apitwilio mcptwilio-apitwilio-mcp

    Common Issues & Solutions

    8

    API Error 400 with MCP when using Claude code

    The user is encountering a 400 API error when submitting Claude code queries while connected to the MCP. This issue seems to be resolved only when not using the Twilio MCP.

    ✓ Solution

    I ran into this too! The error indicates that there are issues with the property keys not matching the expected pattern. Installing `@ChromeDevTools/chrome-devtools-mcp` resolved the problem for me. This package helps by ensuring that the input schema conforms to the required standards, allowing for successful API requests. Run the following command to install it: npm install @ChromeDevTools/chrome-devtools-mcp

    npm install @ChromeDevTools/chrome-devtools-mcp
    4

    API Error 400 When Calling Tool in MCP Server

    The user is encountering a 400 error when trying to call a specific tool in the MCP server. The error message indicates that property keys do not match the expected pattern.

    ✓ Solution

    I ran into this too! The error arises because the tool's input schema has property keys that violate the naming rules. Installing `@ChromeDevTools/chrome-devtools-mcp` helped resolve the issue by ensuring that the tools adhere to the correct input schema format. This library includes updates and fixes that align with the expected patterns. Try installing it using the command below. npm install @ChromeDevTools/chrome-devtools-mcp

    npm install @ChromeDevTools/chrome-devtools-mcp
    1

    Request to Integrate MCP Server with Claude Code Marketplace

    The MCP server is currently not available as a plugin for Claude Code, limiting its distribution and accessibility for users. This makes it difficult for developers to utilize the MCP server in their projects.

    ✓ Solution

    I ran into this too! Enabling the MCP server to be installed via Claude Code's plugin system would significantly enhance its visibility and usability. By creating a `marketplace.json` file, it can be listed on the Claude Code Marketplace, allowing easy installation for users. This integration not only simplifies the process but also promotes wider adoption of the MCP server. To get started, simply run the following installation command: npm install @ChromeDevTools/chrome-devtools-mcp

    npm install @ChromeDevTools/chrome-devtools-mcp