泰尔尼克斯-MCP服务器

Name: 泰尔尼克斯-MCP服务器
Author: team-telnyx

作者：team-telnyx21 星标更新：2025-09-30

安装使用来源：spider==github.com

项目介绍

Telnyx Local Model Context Protocol (MCP) 服务器

⚠️ 已弃用：此基于Python的MCP服务器已弃用。请迁移到官方TypeScript版本：

新仓库：https://github.com/team-telnyx/telnyx-node/tree/master/packages/mcp-server

官方Telnyx本地模型上下文协议（MCP）服务器，支持与强大的电话、消息和AI助手API进行交互。此服务器允许MCP客户端如Claude Desktop、Cursor、Windsurf、OpenAI代理等管理电话号码、发送消息、拨打电话并创建AI助手。

使用Claude Desktop快速开始

在Telnyx门户获取您的API密钥。
安装uvx（Python包管理器），使用curl -LsSf https://astral.sh/uv/install.sh | sh，brew install uv或参见uv仓库以了解其他安装方法。
转到Claude > 设置 > 开发者 > 编辑配置 > claude_desktop_config.json，包含以下内容：

{
  "mcpServers": {
    "Telnyx": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/team-telnyx/telnyx-mcp-server.git", "telnyx-mcp-server"],
      "env": {
        "TELNYX_API_KEY": "<在此插入您的API密钥>"
      }
    }
  }
}

如果您使用的是Windows，您需要在Claude Desktop中启用“开发者模式”。点击左上角汉堡菜单中的“帮助”，然后选择“启用开发者模式”。

下载后运行

在Telnyx门户获取您的API密钥。
安装uvx（Python包管理器），使用curl -LsSf https://astral.sh/uv/install.sh | sh，brew install uv或参见uv仓库以了解其他安装方法。

克隆Git仓库 使用Git下载Telnyx MCP服务器到本地：

git clone https://github.com/team-telnyx/telnyx-mcp-server.git
cd telnyx-mcp-server

使用uvx配置并运行 在您的Claude配置中，您可以使用--from参数引用本地文件夹。例如：

{
  "mcpServers": {
    "Telnyx": {
      "command": "uvx",
      "args": ["--from", "/path/to/telnyx-mcp-server", "telnyx-mcp-server"],
      "env": {
        "TELNYX_API_KEY": "<在此插入您的API密钥>"
      }
    }
  }
}

这会指示Claude从您克隆的文件夹运行服务器。将“/path/to/telnyx-mcp-server”替换为实际的仓库位置。

可用工具

助手工具

创建具有自定义指令和配置的AI助手
列出现有助手
获取助手详情
更新助手属性
删除助手
获取助手TEXML配置

呼叫控制工具

拨打外线电话
结束活跃通话
将呼叫转接到新的目的地
在通话期间播放音频文件
停止音频播放
发送DTMF音调
使用文本转语音功能朗读文本

消息工具

发送SMS和MMS消息
获取消息详情
访问和查看正在进行的SMS对话（resource://sms/conversations）

电话号码工具

列出您的电话号码
购买新的电话号码
更新电话号码配置
列出可用的电话号码

连接工具

列出语音连接
获取连接详情
更新连接配置

云存储工具

创建与Telnyx云存储兼容的存储桶
列出所有区域的存储桶
上传文件
下载文件
列出存储桶中的对象
删除对象
获取存储桶位置信息

嵌入工具

列出现有的嵌入存储桶
抓取并嵌入网站URL
为您自己的文件创建嵌入

密钥管理工具

列出集成密钥
创建新的Bearer或Basic密钥
删除集成密钥

工具过滤

您可以选择性地启用或禁用特定工具。当您只需要可用功能的一部分时，这非常有用。

列出现有工具

要查看所有可用工具：

uvx --from /path/to/telnyx-mcp-server telnyx-mcp-server --list-tools

启用特定工具

您可以仅启用特定工具，使用以下任一方式：

命令行参数：

uvx --from /path/to/telnyx-mcp-server telnyx-mcp-server --tools "send_message,get_message,list_phone_numbers"

环境变量：

{
  "mcpServers": {
    "Telnyx": {
      "command": "uvx",
      "args": ["--from", "/path/to/telnyx-mcp-server", "telnyx-mcp-server"],
      "env": {
        "TELNYX_API_KEY": "<在此插入您的API密钥>",
        "TELNYX_MCP_TOOLS": "send_message,get_message,list_phone_numbers"
      }
    }
  }
}

排除特定工具

您可以排除特定工具，同时启用所有其他工具：

命令行参数：

uvx --from /path/to/telnyx-mcp-server telnyx-mcp-server --exclude-tools "make_call,send_dtmf"

环境变量：

{
  "mcpServers": {
    "Telnyx": {
      "command": "uvx",
      "args": ["--from", "/path/to/telnyx-mcp-server", "telnyx-m-mp-server"],
      "env": {
        "TELNYX_API_KEY": "<在此插入您的API密钥>",
        "TELNYX_MCP_EXCLUDE_TOOLS": "make_call,send_dtmf"
      }
    }
  }
}

示例用法

尝试询问Claude：

"创建一个可以处理电子商务客户服务的AI代理"
"给+5555551234发送一条短信，内容是'您的预约确认为明天下午3点'"
"拨打我的客户+5555551234并将他们转接到我的支持团队"
"找到芝加哥地区代码为312的电话号码"
"使用Telnyx AI助手和语音功能创建自动应答系统"

网络钩子接收器

MCP服务器包括一个网络钩子接收器，可以直接通过ngrok处理Telnyx网络钩子。这对于接收来自Telnyx的呼叫事件和其他通知非常有用。

启用网络钩子

要启用网络钩子接收器，您可以使用--webhook-enabled命令行标志或设置WEBHOOK_ENABLED=true环境变量。如果还提供了NGROK_AUTHTOKEN（参见下文的“ngrok集成”），则在服务器启动时会自动尝试建立ngrok隧道。如果两者都设置了，则命令行标志优先。

使用命令行标志：

telnyx-mcp-server --webhook-enabled --ngrok-enabled

使用环境变量：

或者设置WEBHOOK_ENABLED=true环境变量。这通常在通过MCP客户端设置（参见下文的“Claude Desktop中的网络钩子配置”）或.env文件配置时很方便。

# 用于您的shell示例
export WEBHOOK_ENABLED=true
export NGROK_AUTHTOKEN=your_ngrok_token # ngrok也需要这个
telnyx-mcp-server

ngrok集成

要启用ngrok隧道：

从ngrok.com获取ngrok认证令牌。
设置NGROK_AUTHTOKEN环境变量或使用--ngrok-authtoken标志：

# 使用NGROK_AUTHTOKEN环境变量（推荐）
export NGROK_AUTHTOKEN=your_ngrok_token
telnyx-mcp-server --webhook-enabled # 或使用WEBHOOK_ENABLED=true环境变量

# 或使用--ngrok-authtoken命令行标志
telnyx-mcp-server --webhook-enabled --ngrok-authtoken your_ngrok_token

如果设置了NGROK_AUTHTOKEN，则在启用网络钩子时通常不需要--ngrok-enabled标志。

启用ngrok时，服务器将打印可用于在Telnyx门户中配置网络钩子的公共URL。

重要提示：如果ngrok初始化失败（例如，由于无效的authtoken、网络问题或与其他ngrok进程冲突），MCP服务器将在启动时退出。请检查服务器日志以获取详细信息（参见故障排除部分）。

父进程监控

MCP服务器监控父进程（Claude Desktop），并在父进程消失时自动退出。这确保了即使Claude Desktop意外关闭，资源也能得到妥善清理。

网络钩子监控和运行时控制

您可以通过查询resource://webhook/info资源来检查当前网络钩子和ngrok状态。
要检索收到的网络钩子事件历史记录，请使用get_webhook_events工具。

Claude Desktop中的网络钩子配置

要在Claude Desktop中启用网络钩子，请更新您的配置：

{
  "mcpServers": {
    "Telnyx": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/team-telnyx/telnyx-mcp-server.git", "telnyx-mcp-server"],
      "env": {
        "TELNYX_API_KEY": "<在此插入您的API密钥>",
        "NGROK_AUTHTOKEN": "<在此插入您的ngrok令牌>",
        "WEBHOOK_ENABLED": "true", // 通过环境变量启用网络钩子
        // 或者，您可以在"args"中使用命令行标志而不是在env中使用WEBHOOK_ENABLED：
        // 例如，"args": ["--from", "git+https://github.com/team-telnyx/telnyx-mcp-server.git", "telnyx-mcp-server", "--webhook-enabled"],
      }
    }
  }
}

网络钩子示例

远程MCP现已提供

Telnyx现在提供基于最新MCP规范的远程MCP实现。这允许您通过远程托管的MCP服务器访问Telnyx的强大通信API。无需在本地运行服务器。更多详情请参阅官方文档。

贡献

如果您想贡献或从源码运行：

克隆仓库：

git clone https://github.com/team-telnyx/telnyx-mcp-server.git
cd telnyx-mcp-server

创建虚拟环境并使用uv安装依赖项：

uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"  # 包括开发依赖项如ruff

创建一个.env文件并添加您的Telnyx API密钥：

echo "TELNYX_API_KEY=YOUR_API_KEY" > .env

运行测试以确保一切正常：

pytest

在Claude Desktop中安装服务器：mcp install src/telnyx_mcp_server/server.py
使用MCP Inspector进行本地调试和测试：mcp dev src/telnyx_mcp_server/server.py

使用Ruff进行代码质量检查

本项目使用Ruff进行Python代码的检查和格式化。Ruff是一个用Rust编写的快速Python检查器和格式化器，旨在用单一统一工具替代多个Python代码质量工具。

安装Ruff

Ruff包含在开发依赖项中。使用以下命令安装它：

uv pip install -e ".[dev]"

使用Ruff

检查

要检查您的代码是否存在问题：

ruff check .

要自动修复可能的问题：

ruff check --fix .

格式化

要格式化您的代码：

ruff format .

提交前工作流

为了获得最佳开发体验，在提交更改之前运行这些命令：

# 格式化代码
ruff format .

# 修复检查问题
ruff check --fix .

# 运行测试
pytest

配置

Ruff在pyproject.toml文件中配置。配置包括：

基于PEP 8的代码风格规则
导入排序
文档字符串样式检查（Google风格）
代码复杂度检查
更多

请参阅pyproject.toml中的[tool.ruff]部分以获取完整的配置。

故障排除

在使用Claude Desktop运行时的日志可以在以下位置找到：

Windows：%APPDATA%\Claude\logs\mcp-server-telnyx.log
macOS：~/Library/Logs/Claude/mcp-server-telnyx.log

MCP Telnyx: spawn uvx ENOENT

如果您遇到错误"MCP Telnyx: spawn uvx ENOENT"，请通过运行以下命令在终端中确认其绝对路径：

which uvx

一旦您获得了绝对路径（例如，/usr/local/bin/uvx），请更新您的配置以使用该路径（例如，"command": "/usr/local/bin/uvx"）。这确保了正确的可执行文件被引用。

服务器无法启动（尤其是启用网络钩子/ngrok时）

如果MCP服务器无法启动，特别是启用网络钩子时，可能是由于ngrok初始化问题。常见原因是后台存在ngrok进程，可能是从前一个未干净关闭的服务器实例遗留下来的。

检查正在运行的进程：使用命令如ps aux | grep telnyx-mcp-server（Linux/macOS）或检查任务管理器（Windows）查找任何残留的telnyx-mcp-server进程。由于ngrok由服务器内部管理，通常不会看到单独的'ngrok'进程。
终止旧进程：如果发现，请终止这些旧进程。
检查日志：查看服务器日志（上述位置）以获取与ngrok或服务器启动相关的具体错误信息。