ElevenLabs Agents

@mindstone/mcp-server-elevenlabs-agents

面向 Model Context Protocol 主机的 ElevenLabs Conversational AI MCP 服务。通过 ElevenLabs ConvAI API 检查和编写语音 Agent、查看对话文字记录和录音、管理电话号码分配、拨打外呼电话、提交或监控定时批量呼叫，以及写入知识库。

状态

• 版本： 0.2.1 · npm
• 身份验证： API 密钥（ELEVENLABS_API_KEY）
• 工具： 31（配置、Agent、Agent 工具、对话、电话号码、外呼、批量呼叫、知识库）
• 接口： cloud-api
• 机器可读： STATUS.json

要求

• Node.js 20+
• npm
• 具有 Conversational AI 访问权限的 ElevenLabs API 密钥

一键安装

点击按钮后，主机将提示你填写：ELEVENLABS_API_KEY。

{
  "mcpServers": {
    "ElevenLabs Agents": {
      "command": "npx",
      "args": [
        "-y",
        "@mindstone/mcp-server-elevenlabs-agents"
      ],
      "env": {
        "ELEVENLABS_API_KEY": ""
      }
    }
  }
}

快速开始

安装和构建

cd <path-to-repo>/connectors/elevenlabs-agents
npm install
npm run build

本地运行

node dist/index.js

配置

环境变量

• ELEVENLABS_API_KEY — ElevenLabs API 密钥（以 sk_ 开头）
• MCP_WORKSPACE_PATH — 可选的知识库文件上传沙盒根目录
• MCP_HOST_BRIDGE_STATE — 用于凭据管理的主机桥接状态文件的可选路径
• MINDSTONE_REBEL_BRIDGE_STATE — MCP_HOST_BRIDGE_STATE 的向后兼容别名

主机配置示例

{
  "mcpServers": {
    "ElevenLabs Agents": {
      "command": "node",
      "args": ["<path-to-repo>/connectors/elevenlabs-agents/dist/index.js"],
      "env": {
        "ELEVENLABS_API_KEY": "your-api-key"
      }
    }
  }
}

工具（31）

配置

• configure_elevenlabs_agents_api_key — 保存 ElevenLabs API 密钥

Agent

• list_agents — 列出工作区中的语音 Agent
• get_agent — 获取一个 Agent，包括提示词和嵌套的对话配置
• create_agent — 通过便于用户使用的编写界面创建新 Agent
• update_agent — 使用 PATCH 深度合并语义部分更新一个 Agent
• duplicate_agent — 复制现有 Agent 后再进行试验
• delete_agent — 永久删除一个 Agent
• simulate_conversation — 在进行电话工作前，用模拟的用户消息测试 Agent

Agent 工具（工作区工具）

• list_agent_tools — 列出 Agent 可用的 webhook / 客户端 / 系统工具
• add_agent_tool — 向工作区添加 webhook 或客户端工具

对话

• list_conversations — 列出对话，可按 Agent / 日期 / 成功状态筛选
• get_conversation — 获取完整的对话文字记录和分析
• get_conversation_audio — 将对话录音下载到临时文件
• submit_conversation_feedback — 对已查看的对话提交赞 / 踩反馈

Phone numbers

• list_phone_numbers — 列出已配置的电话号码
• get_phone_number — 获取一个电话号码及其标签／分配信息
• import_phone_number — 将 Twilio 或 SIP 中继号码导入工作区
• update_phone_number — 更新一个电话号码的标签和／或分配的 Agent
• delete_phone_number — 永久移除已导入的电话号码

Outbound calls

• make_outbound_call — 自动确定电话号码提供商后拨打一通外呼电话

Batch calls

• submit_batch_call — 提交包含多个接收方的批次，可选择安排在未来执行
• list_batch_calls — 列出工作区中最近的批量呼叫任务
• get_batch_call — 查看一个批量任务，包括每个接收方的状态
• cancel_batch_call — 取消排队中或已安排的批量任务
• retry_batch_call — 重试之前提交的批量任务

Knowledge base

• list_knowledge_base_docs — 列出知识库文档
• get_knowledge_base_doc — 获取一个知识库文档（元数据 + /content 正文，上限约为 50 KB）
• add_knowledge_base_document — 以文本、文件或 URL 模式添加知识库文档
• delete_knowledge_base_document — 删除知识库文档，可选择强制删除
• get_knowledge_base_rag_index_status — 检查文档是否已建立索引且可检索
• rebuild_knowledge_base_rag_index — 触发知识库文档的索引或重新索引

安全说明

ElevenLabs API 返回的所有外部文本都会先用 <untrusted-content> 信封包裹，再传给模型。这对于对话转录尤其重要，因为其中可能包含由攻击者控制的来电者语音内容。信封机制采用默认拒绝策略：任何不属于已识别结构化值（ID、枚举值、时间戳、电话号码）的内容都会被包裹，包括根节点是裸 JSON 值而非对象的响应。

同样的遍历机制会应用于所有响应面——Agent、对话、知识库、电话号码、模拟以及外呼／批量呼叫。没有任何响应面会维护已知自然语言字段名称列表，因此上游新增的文本字段（Agent 名称、工作流分支名称、未来的摘要）从首次出现在响应中起就会被包裹。

意外的结构也不会让文本绕过遍历。根节点是裸 JSON 值的响应、元素为裸字符串的列表，以及在预期应为轮次数组的位置上包含字符串或对象的转录字段，都会经过同样的默认拒绝遍历，而不会原样返回。

由于读取结果会被信封包裹，Agent 编辑工具会从收到的值中剥去一层信封。因此，将 get_agent 返回的语言、模型 ID、提示词或 advanced_config 片段复制到 update_agent 中，存储到上游的仍是原始文本，而不是包裹它的信封。 遍历中的结构字面量豁免会同时检查路径和值形状，而非仅依据键名。在任意由协作者编写的映射中——Webhook 的 request_headers、advanced_config 透传内容、JSON Schema 参数片段，以及随调用发起一同提交、由调用方编写的开放映射（conversation_initiation_client_data、conversation_config_override、custom_llm_extra_body、overrides，ElevenLabs 会在会话、调用和批量调用接口中反映这些映射）——键名是数据，而非架构，因此其中的字符串一律不会保留为字面量：请求头映射中名为 status 的属性是协作者文本，不是受信任的枚举，无论其值看起来如何，都会被封装。由于 advanced_config 会在发送到上游之前深度合并到配置正文中，其反映出的结构不包含可据以判断的 advanced_config 祖先键；在 Agent 和工作区工具接口中，只有当从接口根节点开始的每个祖先键都处于已知架构位置时，字符串才会保留为字面量，因此扁平化的透传片段（例如 tool_config.custom.status）无论键名和取值看起来多么符合结构特征，都会被封装。在其他受信任路径中，id／status／role／type 键下的字符串只有在符合 ID／枚举格式时才会保留为字面量（不得含空格、: 或 /，且不能呈现短语特征，也不能由塑造指令的词语构成——仅凭字符形状无法区分标识符和不含空格的编写文本，例如 IGNORE_PRIOR_INSTRUCTIONS）；timestamp 键下的字符串只有符合 ISO-8601 格式时才会保留为字面量；电话号码键下的字符串则只有符合 E.164 格式时才会保留。凭据形式键（token、sid、*_secret、*_password、*_api_key）下的值会替换为 [redacted]，而不会被传递；此外，import_phone_number 还会从任何反映凭据的成功响应内容或上游错误详情中剔除确切提交的凭据——Twilio SID／令牌对，以及 SIP 中继凭据值（例如中继用户名）。

连接器要求 ElevenLabs 在服务器端获取的 URL 必须是公开的 https:// 地址。这包括通过 add_agent_tool 添加的 Webhook 工具、URL 模式的知识库文档，以及 Agent 编写工具 advanced_config（create_agent／update_agent）中每个以 url 为键的字符串——ElevenLabs 会在每轮对话中获取 custom_llm.url，并解析 platform_settings 中的 Webhook URL，因此在发出任何上游调用之前，都会递归验证合并后的 Agent 正文。非 HTTP 协议、普通 HTTP、内嵌凭据、环回／私有／链路本地／CGNAT／多播 IP 字面量（包括云元数据地址 169.254.169.254）、IPv4 映射／NAT64／6to4／Teredo 和文档用途 IPv6 地址段、localhost 类型的主机名，以及单标签主机名，都会在发出任何上游调用之前被拒绝；分类前会去除根标签末尾的点，因此 localhost. 等 DNS 等价写法也会被拒绝。ElevenLabs 获取 URL 后，公开主机名仍可能解析到内部地址或重定向到内部地址——这种剩余的 DNS／重定向信任边界是服务器端解析固有的，无法通过此验证消除。add_agent_tool 的 advanced_config 最后进行深度合并，但不能设置一级字段（type、name、description、expects_response、api_schema.url、api_schema.method）；发送前还会重新验证合并后的工具配置。

发送到上游之前，会以 E.164 格式验证外呼号码。即使客户端应用已关闭，计划批次仍会在 ElevenLabs 服务器上运行，因此应使用 list_batch_calls／get_batch_call 监控，并在需要时使用 cancel_batch_call 停止。

许可证

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