home / mcp / telnyx mcp server

Telnyx MCP Server

Official Telnyx Local Model Context Protocol (MCP) Server that enables interaction with powerful telephony, messaging, and AI assistant APIs. This server allows MCP clients like Claude Desktop, Cursor, Windsurf, OpenAI Agents and others to manage phone numbers, send messages, make calls, and create AI assistants.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "team-telnyx-telnyx-mcp-server": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/team-telnyx/telnyx-mcp-server.git",
        "telnyx-mcp-server"
      ],
      "env": {
        "TELNYX_API_KEY": "<insert-your-api-key-here>",
        "NGROK_AUTHTOKEN": "YOUR_NGROK_TOKEN",
        "WEBHOOK_ENABLED": "true"
      }
    }
  }
}

You can run and connect to a Telnyx MCP Server locally to manage numbers, messages, calls, and AI assistants from your MCP clients. This server lets you leverage Telnyx APIs through a local or remote MCP workflow, with flexible tooling and webhook support for real-time events.

How to use

Use an MCP client (such as Claude Desktop or other MCP-enabled apps) to interact with the Telnyx MCP Server. You configure the client to start the MCP server process locally or point to a remote MCP server, then you can create, list, and manage assistants, handle phone numbers, send messages, make calls, and control cloud storage, embeddings, and secrets through the available tools. Enable webhooks if you want to receive call events and other notifications, and optionally run ngrok to expose a public webhook URL.

How to install

Prerequisites: you need Python-based tooling and a compatible MCP runtime. You will also install a local MCP server and a package manager to run the MCP process.

# Prerequisites
# 1) Ensure Python and the uvx helper are available
# 2) Install uvx (Python package manager) via your preferred method
# 3) Have a Telnyx API key ready

# Step 1: Get your Telnyx API key (from the Telnyx Portal) and store it securely
export TELNYX_API_KEY=YOUR_API_KEY

# Step 2: Clone the MCP server repository locally
git clone https://github.com/team-telnyx/telnyx-mcp-server.git
cd telnyx-mcp-server

# Step 3: Run the MCP server using uvx from your local copy
uvx --from /path/to/telnyx-mcp-server telnyx-mcp-server

# When configuring via Claude Desktop, you can reference the local folder as shown in the example below

Configuration examples for MCP clients

{
  "mcpServers": {
    "Telnyx": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/team-telnyx/telnyx-mcp-server.git", "telnyx-mcp-server"],
      "env": {
        "TELNYX_API_KEY": "<insert-your-api-key-here>"
      }
    }
  }
}

Additional local run configuration

If you prefer to run the MCP server from a locally cloned folder, use this variant in your client configuration.

{
  "mcpServers": {
    "Telnyx": {
      "command": "uvx",
      "args": ["--from", "/path/to/telnyx-mcp-server", "telnyx-mcp-server"],
      "env": {
        "TELNYX_API_KEY": "<insert-your-api-key-here>"
      }
    }
  }
}

Available tools

create_assistant

Create AI assistants with custom instructions and configurations

list_assistants

List existing AI assistants and their details

get_assistant

Get details of a specific AI assistant

update_assistant

Update properties of an existing AI assistant

delete_assistant

Delete an AI assistant

get_texml_config

Get TEXML configuration for an assistant

make_call

Make outbound phone calls

hangup_call

Hang up an active call

transfer_call

Transfer a call to a new destination

play_audio

Play an audio file during a call

stop_audio

Stop audio playback during a call

send_message

Send SMS/MMS messages

get_message

Get message details

list_sms_conversations

List ongoing SMS conversations (resource://sms/conversations)

list_phone_numbers

List your phone numbers

buy_phone_number

Buy new phone numbers

update_phone_number

Update phone number configurations

list_connections

List voice connections

get_connection

Get connection details

update_connection

Update connection configurations

create_bucket

Create Telnyx Cloud Storage buckets

list_buckets

List buckets across regions

upload_file

Upload files to a bucket

download_file

Download files from a bucket

list_objects

List objects in a bucket

delete_object

Delete objects from a bucket

get_bucket_location

Get bucket location information

list_embeddings

List existing embedded buckets

embed_site

Scrape and embed a website URL

create_embeddings

Create embeddings for your own files

list_secrets

List integration secrets

create_secret

Create new secrets

delete_secret

Delete integration secrets