Retell AI

@mindstone/mcp-server-retell-ai

通过 Retell AI API 管理语音 Agent 电话、批量呼叫活动、通话、Agent 配置、大模型提示词、知识库、聊天记录和语音发现。

最适合希望使用本地语音操作连接器来拨打电话、查看通话记录，并在用户确认后调整 Agent 提示词的 MCP 宿主。

状态

• 版本： 0.3.0 · npm
• 身份验证： API 密钥（RETELL_API_KEY）
• 工具： 32（通话、Agent、大模型、语音、知识库、聊天）
• 接口： cloud-api
• 机器可读： STATUS.json

存在的原因

Retell 托管的 MCP 服务最适合支持通过 HTTP 使用远程 MCP 的客户端。此软件包面向本地 stdio 宿主，让它们能够通过与此仓库其余部分相同的 npm 连接器流程使用 Retell 语音操作。

它将语音 Agent 工作转化为清晰的助手工作流：检查 Agent 和提示词，选择合适的电话号码，拨打电话或创建网络通话，然后监控结果。其价值不只是提供 API 访问；它还有助于确保真实通话操作审慎、可审核，并与正确的 Agent 配置关联。

交互示例

“使用我们的支持 Agent 给 Jane 打电话，确认她明天的预约。”

宿主调用的工具：

1. list_agents — 查找支持 Agent 及其 Agent ID。
2. get_retell_llm — 检查提示词和支持的动态变量。
3. list_phone_numbers — 查找已注册的外拨号码。
4. create_phone_call — 在宿主／用户确认后拨打电话。
5. get_call — 检查通话状态、转录文本和录音详情。

响应（节选）：

{
  "ok": true,
  "call_id": "call_01HXX...",
  "status": "registered",
  "from_number": "+14155551234",
  "to_number": "+14155559876",
  "warnings": []
}

要求

• Node.js 20+
• npm
• Retell AI API 密钥。

一键安装

点击按钮后，宿主会提示你填写：RETELL_API_KEY。

{
  "mcpServers": {
    "Retell AI": {
      "command": "npx",
      "args": [
        "-y",
        "@mindstone/mcp-server-retell-ai"
      ],
      "env": {
        "RETELL_API_KEY": ""
      }
    }
  }
}

快速开始

安装并构建

cd <path-to-repo>/connectors/retell-ai
npm install
npm run build

npx

npx -y @mindstone/mcp-server-retell-ai

本地

node dist/index.js

配置

设置以下环境变量：

MCP 主机配置

{
  "mcpServers": {
    "retell-ai": {
      "command": "npx",
      "args": ["-y", "@mindstone/mcp-server-retell-ai"],
      "env": {
        "RETELL_API_KEY": "your-api-key"
      }
    }
  }
}

安全说明

外呼需要主机确认

create_phone_call 被标记为现实世界操作。MCP 主机在调用前必须 要求用户明确确认。 外呼按分钟计费，费用从你的 Retell AI 套餐中扣除；拨错电话会造成 无法撤销的现实后果（陌生人的电话会响起、通话会被录音、 你的账户会被扣费）。

集成此连接器的主机必须：

• 在每次调用前向用户显示拟用的 from_number 和 to_number。
• 在用户明确确认前阻止通话。
• 绝不能根据先前的批准自动批准 create_phone_call——每次通话 都必须单独确认。

在发出任何上游请求前，都会根据 E.164 正则表达式 /^\+[1-9]\d{1,14}$/ 验证 from_number 和 to_number。号码必须：

• 以 + 开头，后接 1-9 的国家代码数字（不能以 0 开头）。
• 只能包含数字——空格、连字符和括号均不允许。
• 总长度为 2 至 15 位，包含国家代码。

格式错误的号码会在本地被拒绝，并返回结构化的 INVALID_PHONE_NUMBER 错误，绝不会发送到上游。

批量呼叫会扩大影响范围

create_batch_call 会针对每项任务拨打一通真实且计费的电话。与 create_phone_call 相同的确认规则适用于整个批次：主机 必须向用户显示完整的收件人列表（from_number 加上每个 to_number）， 并在调用前获得用户明确确认。可以考虑先检查 get_concurrency，以免营销活动挤占呼入容量。

知识库文件上传受工作区沙箱限制

create_knowledge_base 和 add_knowledge_base_sources 接受本地 file_paths。读取范围受限于 MCP_WORKSPACE_PATH（若未设置，则使用系统 临时目录），并通过规范路径前缀包含关系进行限制：.. 路径遍历、沙箱外的绝对路径，以及逃逸出沙箱的符号链接，都会在读取磁盘前被拒绝。读取采用先打开再验证的方式： 连接器会打开一个文件描述符，确认已打开的 inode 就是沙箱批准的文件，通过该描述符读取，然后在读取后再次检查该 描述符——如果文件在验证和读取之间被交换、替换或修改，操作将安全失败；50MB 的限制则按 实际读取的字节数执行。Retell 将上传限制为最多 25 个文件，每个文件 50MB。

动态变量的通话前验证会显示结果且有执行顺序

create_phone_call、create_web_call 和 create_batch_call 会在创建 通话／会话／营销活动之前，根据实时提示词验证传入的 retell_llm_dynamic_variables，并以有效的 (agent_id, agent_version) 为键，确保验证的提示词就是将要运行的提示词。 此项检查绝不会阻止明确请求的通话，但也绝不会静默失败：未匹配的变量、无法识别的提示词（例如 对话流 Agent）以及查找失败，都会作为明确的 warnings 显示在工具响应中。

删除工具不可逆

delete_agent、delete_retell_llm 和 delete_phone_number 均不可逆：删除 Agent 和 LLM 会移除所有版本，而已删除的 电话号码会被释放（你可能无法重新获得相同号码）。主机应要求用户明确确认，并建议先检查绑定关系（list_phone_numbers、get_agent）。

配置变更也需要审核

该连接器还将 Agent 创建／更新、Agent 发布、LLM 提示词创建／更新、电话号码更新、Web 通话创建、停止进行中的通话以及 API 密钥配置标记为需要审核的操作。主机应谨慎处理这些操作，因为它们可能会改变实时通话行为、费用或凭据。

工具（32）

电话呼叫

• create_phone_call — 使用 Retell AI 语音 Agent 创建外呼
• create_web_call — 与 Retell AI Agent 创建基于浏览器的语音通话
• get_call — 获取特定通话的详细信息（状态、转录文本、录音）
• list_calls — 按 Agent、时间范围或状态列出并筛选通话
• stop_call — 终止正在进行的通话
• get_concurrency — 在批量或突发呼叫前检查账户的呼叫容量余量

批量呼叫

• create_batch_call — 安排或启动外呼活动（一个 from_number，多个接收者）

Agent

• get_agent — 获取语音 Agent 的完整配置
• list_agents — 列出已配置的语音 Agent（分页）
• create_agent — 创建新的语音 Agent
• update_agent — 更新现有 Agent 的配置
• publish_agent — 发布 Agent 草稿，使其可用于呼叫
• get_agent_versions — 列出 Agent 的版本历史
• delete_agent — 永久删除 Agent 及其所有版本

LLM 配置

• update_retell_llm — 更新 LLM 配置（提示词、问候语、模型）
• get_retell_llm — 获取完整的 LLM 配置
• create_retell_llm — 创建新的 LLM 配置
• list_retell_llms — 列出所有 LLM 配置
• delete_retell_llm — 永久删除 LLM 配置及其所有版本

知识库

• list_knowledge_bases — 列出知识库及其处理状态
• get_knowledge_base — 获取知识库的来源和状态
• create_knowledge_base — 根据文本、URL 和/或沙盒化本地文件创建知识库
• add_knowledge_base_sources — 向现有知识库添加文本、URL 或文件

聊天

• list_chat_agents — 列出已配置的聊天 Agent（分页）
• list_chats — 按 Agent 或时间范围列出并筛选聊天会话
• get_chat — 获取聊天的完整转录文本和分析结果

发现

• list_voices — 列出可用的文本转语音音色
• list_phone_numbers — 列出已注册的电话号码
• get_phone_number — 获取特定电话号码的详细信息
• update_phone_number — 更新电话号码的 Agent 分配
• delete_phone_number — 永久释放电话号码

配置

• configure_retell_api_key — 保存你的 Retell AI API 密钥

供应商弃用动态

Retell 会在短时间内发布不兼容的端点变更——此连接器已迁移两次（0.2.0 版中的 v2/v3 通话端点调整，以及 2026-07-31 弃用后将 list_agents 改为统一的 POST /v2/list-agents）。维护者：每次发布前，以及此前正常工作的工具出现无法解释的 404/410 错误后，都请重新查看 Retell 弃用通知。已知的即将发生的变更：“Update Call 仅限已结束的通话”（2026-08-31）——此连接器未提供 update-call，因此目前无需采取任何行动。

许可证

FSL-1.1-MIT — Functional Source License，Version 1.1，未来转为 MIT 许可证。该软件将于 2030-04-08 转为 MIT 许可证。