Telnyx MCP

Telnyx本地模型上下文协议（MCP）服务器

⚠️ 已弃用这个基于Python的MCP服务器已弃用。请迁移到官方的TypeScript版本： 新仓库： https://github.com/team-telnyx/telnyx-node/tree/master/packages/mcp-server 翻译为中文是：“https://github.com/team-telnyx/telnyx-node 仓库中的 master 分支下的 packages/mcp-server 目录”

______________________________________________________________________

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

快速入门Claude桌面版

1. 从（某处）获取您的API密钥 Telnyx门户.
2. 安装 uvx (Python包管理器)，使用以下命令安装： curl -LsSf https://astral.sh/uv/install.sh | sh ， brew install uv 或者查看 uv 仓库中提供了其他安装方法。
3. 前往 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": ""
      }
    }
  }
}

如果你使用的是Windows系统，你需要在Claude桌面版中启用“开发者模式”才能使用MCP服务器。点击左上角汉堡菜单中的“帮助”，然后选择“启用开发者模式”。

下载后运行

1. 从（某处）获取您的API密钥 Telnyx门户.

1. 安装 uvx (Python 包管理器)，使用以下命令安装： curl -LsSf https://astral.sh/uv/install.sh | sh ， brew install uv 或者查看 uv 用于获取更多安装方法的仓库。

1. 克隆Git仓库\

使用 Git 在本地下载 Telnyx MCP 服务器：

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

1. 使用uvx进行配置并运行\

在你的Claude配置中，你可以通过使用（路径）来引用本地文件夹 --from 论点。例如：

   {
     "mcpServers": {
       "Telnyx": {
         "command": "uvx",
         "args": ["--from", "/path/to/telnyx-mcp-server", "telnyx-mcp-server"],
         "env": {
           "TELNYX_API_KEY": ""
         }
       }
     }
   }

1. 这条指令告诉Claude从你克隆的文件夹中运行服务器。

将“/path/to/telnyx-mcp-server”替换为实际的仓库位置。

可用工具

辅助工具

• 创建带有自定义指令和配置的人工智能助手
• 列出现有的助手
• 获取助手详情
• 更新助手属性
• 删除助手
• 获取TEXML助手配置

呼叫控制工具

• 进行外呼电话
• 挂断正在进行的通话
• 将呼叫转接至新目的地
• 在通话期间播放音频文件
• 停止音频播放
• 发送DTMF音调
• 使用文本转语音功能朗读文本

消息工具

• 发送短信和彩信
• 获取消息详情
• 访问并查看正在进行的短信对话resource://sms/conversations)

电话号码工具

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

连接工具

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

云存储工具

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

嵌入工具

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

Secrets Manager 工具

• 列出集成密钥
• 创建新的承载者或基本密钥
• 删除集成密钥

工具过滤

在运行MCP服务器时，您可以选择性地启用或禁用特定工具。当您只需要使用可用功能的一部分时，这一点非常有用。

列出可用工具

查看所有可用工具：

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

启用特定工具

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

1. 命令行参数:

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

1. 环境变量：

   {
     "mcpServers": {
       "Telnyx": {
         "command": "uvx",
         "args": ["--from", "/path/to/telnyx-mcp-server", "telnyx-mcp-server"],
         "env": {
           "TELNYX_API_KEY": "",
           "TELNYX_MCP_TOOLS": "send_message,get_message,list_phone_numbers"
         }
       }
     }
   }

排除特定工具

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

1. 命令行参数：

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

1. 环境变量：

   {
     "mcpServers": {
       "Telnyx": {
         "command": "uvx",
         "args": ["--from", "/path/to/telnyx-mcp-server", "telnyx-mcp-server"],
         "env": {
           "TELNYX_API_KEY": "",
           "TELNYX_MCP_EXCLUDE_TOOLS": "make_call,send_dtmf"
         }
       }
     }
   }

示例用法

试试问问克劳德：

• “创建一个能够处理电子商务业务客户服务的人工智能代理”
• “给+5555551234发送一条短信，内容为‘您的预约已确认，时间为明天下午3点’”
• “请致电我的客户，号码是+5555551234，并将他们转接给我的支持团队。”
• “帮我找一个芝加哥的电话号码，区号是312”
• “利用Telnyx AI助手和语音功能创建一个自动应答系统”

Webhook 接收器

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

启用Webhooks

要启用webhook接收器，您可以使用 --webhook-enabled 命令行标志或设置 WEBHOOK_ENABLED=true 环境变量。如果一个 NGROK_AUTHTOKEN 同时也提供了该功能（见下文“Ngrok 集成”部分），当服务器启动时，将自动尝试建立 Ngrok 隧道。如果两者都已设置，则命令行标志具有优先权。

使用命令行标志：

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

使用环境变量：

或者，设置为 WEBHOOK_ENABLED=true 环境变量。当通过MCP客户端设置（见下文“Claude桌面中的Webhook配置”）或在（其他配置场景中）进行配置时，这通常非常方便 .env 文件。

# Example for your shell
export WEBHOOK_ENABLED=true
export NGROK_AUTHTOKEN=your_ngrok_token # Also needed for ngrok
telnyx-mcp-server

Ngrok 集成

要启用ngrok隧道功能：

1. 从（某处）获取ngrok认证令牌 ngrok.com（注：这是一个用于创建安全隧道的网站名称，在中文中通常直接保留原名，不进行翻译。）
2. 设置 NGROK_AUTHTOKEN 环境变量或使用 --ngrok-authtoken 标志：

# Using NGROK_AUTHTOKEN environment variable (recommended)
export NGROK_AUTHTOKEN=your_ngrok_token
telnyx-mcp-server --webhook-enabled # Or use WEBHOOK_ENABLED=true env var

# Or using --ngrok-authtoken command line flag
telnyx-mcp-server --webhook-enabled --ngrok-authtoken your_ngrok_token

如果 NGROK_AUTHTOKEN （如果）已设置，则 --ngrok-enabled 当网络钩子（webhooks）处于激活状态时，通常不需要标志（flag）。

当启用ngrok时，服务器将打印出一个公共URL，该URL可用于在Telnyx门户中配置webhooks。

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

父进程监控

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

Webhook 监控与运行时控制

• 您可以查询以检查当前的webhook和ngrok状态 resource://webhook/info 资源。
• 要检索已接收的webhook事件历史记录，请使用 get_webhook_events 工具。

Claude Desktop中的Webhook配置

要在 Claude Desktop 中启用 Webhooks，请更新您的配置：

{
  "mcpServers": {
    "Telnyx": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/team-telnyx/telnyx-mcp-server.git", "telnyx-mcp-server"],
      "env": {
        "TELNYX_API_KEY": "",
        "NGROK_AUTHTOKEN": "",
        "WEBHOOK_ENABLED": "true", // Enables webhooks via environment variable
        // Alternatively, you can use command-line flags in "args" instead of WEBHOOK_ENABLED in env:
        // e.g., "args": ["--from", "git+https://github.com/team-telnyx/telnyx-mcp-server.git", "telnyx-mcp-server", "--webhook-enabled"],
      }
    }
  }
}

Webhook 示例

（此句为原文的重复，无实际意义，若需翻译此重复句，则为）

远程MCP现已可用

Telnyx 现在提供了一种基于最新MCP规范的远程MCP实现。这使您能够通过远程托管的MCP服务器访问Telnyx的强大通信API。无需在本地运行服务器。更多信息请见 官方文件。

贡献；做出贡献

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

1. 克隆仓库：

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

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

uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"  # Includes development dependencies like ruff

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

echo "TELNYX_API_KEY=YOUR_API_KEY" > .env

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

pytest

1. 在Claude Desktop中安装服务器： mcp install src/telnyx_mcp_server/server.py
2. 使用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 .

预提交工作流程

为了获得最佳的开发体验，请在提交更改前运行以下命令：

# Format code
ruff format .

# Fix linting issues
ruff check --fix .

# Run tests
pytest

配置

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

• 基于PEP 8的代码风格规则
• 进口货物分类
• 文档字符串风格检查（谷歌风格）
• 代码复杂度检查
• 以及更多

查看 [tool.ruff] （位于）...的部分 pyproject.toml 对于完整配置。

故障排除

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

• Windows： %APPDATA%\Claude\logs\mcp-server-telnyx.log
• macOS（苹果电脑操作系统）： ~/Library/Logs/Claude/mcp-server-telnyx.log

MCP Telnyx: 启动 uvx 时 ENOENT 错误

如果你遇到错误“MCP Telnyx: spawn uvx ENOENT”，请在终端运行以下命令来确认其绝对路径：

which uvx

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

服务器启动失败（尤其是使用Webhooks/Ngrok时）

如果MCP服务器无法启动，特别是当您已启用webhooks时，可能是由于ngrok初始化出现了问题。 一个常见的原因是后台运行着一个现有的ngrok进程，这个进程可能来自之前没有正常关闭的服务器实例。

• 检查正在运行的进程： 使用诸如……之类的命令 ps aux | grep telnyx-mcp-server (Linux/macOS) 或检查任务管理器 (Windows) 查看是否有任何残留进程 telnyx-mcp-server 进程。由于ngrok由服务器内部管理，因此通常不会看到单独的“ngrok”进程。
• 终止旧进程： 如果找到，终止这些旧进程。
• 检查日志： 检查服务器日志（上述位置）中与ngrok或服务器启动相关的具体错误信息。