twelvelabs-mcp-server

TwelveLabs MCP 服务

本项目与 TwelveLabs（视频理解平台）无关。 它是一个用于 ElevenLabs Conversational AI API 的 MCP 服务，涵盖语音 Agent、知识库、对话和 TTS。“TwelveLabs”仅是本项目的代号。

这是一个增强型 MCP（Model Context Protocol）服务，可让任何兼容的 MCP 客户端直接访问 ElevenLabs Conversational AI API，包括官方 ElevenLabs MCP 连接器未提供的功能。

涵盖内容

• Agent —— 列出 Agent、获取完整配置（包括大模型和温度）、更新提示词/设置、管理 Webhook 和文件上传
• 知识库 —— 列出、读取完整内容、添加文本/URL 文档、删除文档
• 对话 —— 筛选和标记历史记录、检查转录文本，以及重新运行通话后分析/评估
• 语音 —— 列出和搜索可用语音

先决条件

• Node.js >= 18
• ElevenLabs API 密钥 —— 在 elevenlabs.io 获取

快速开始

选项 A：npx（无需克隆）

ELEVENLABS_API_KEY=your-key npx twelvelabs-mcp-server

选项 B：克隆并构建

git clone https://github.com/micro-JAY/twelvelabs-mcp-server.git
cd twelvelabs-mcp-server
npm install --include=dev
npm run build

连接 MCP 客户端

在 MCP 客户端的配置中添加一个等效的服务条目。配置文件的位置和周边语法因客户端而异；以下是标准的 stdio 服务定义：

{
  "mcpServers": {
    "twelvelabs": {
      "command": "node",
      "args": ["/path/to/twelvelabs-mcp-server/dist/index.js"],
      "env": {
        "ELEVENLABS_API_KEY": "your-api-key-here"
      }
    }
  }
}

重启或重新连接 MCP 客户端。你应该会在可用工具列表中看到 twelvelabs。

使用方法

让支持 MCP 的助手使用这些工具，例如：

“列出我的 Agent” “获取 agent_1001kjbh14xce5kbreh55ydf4rae 的完整配置” “显示该 Agent 最近的 10 条对话” “获取 conversation_xyz 的转录文本和分析结果”

兼容性

此服务适用于支持 stdio 传输方式，并允许为本地服务进程配置环境变量的 MCP 客户端。仅支持远程 HTTP MCP 服务的客户端需要使用兼容的 stdio 桥接或代理。

工具参考

Agent 工具

工具	功能
twelvelabs_list_agents	列出账户中的所有 Agent
twelvelabs_get_agent	完整配置：大模型、语音、知识库文档、Webhook、提示词预览
twelvelabs_get_agent_prompt	完整且未截断的系统提示词文本
twelvelabs_update_agent_prompt	替换系统提示词和/或第一条消息
twelvelabs_update_agent_settings	更改温度、语音、TTS 设置、语言
twelvelabs_update_agent_conversation_capabilities	启用聊天文件上传并设置最长时长消息
twelvelabs_list_agent_conversations	某个 Agent 的近期对话
twelvelabs_get_agent_webhook	当前 Webhook URL
twelvelabs_set_agent_webhook	设置或移除 Webhook URL

知识库工具

工具	功能
twelvelabs_list_kb_docs	列出所有知识库文档及其大小和创建日期
twelvelabs_get_kb_doc	文档中提取的完整文本内容
twelvelabs_add_kb_text	添加纯文本文档
twelvelabs_add_kb_url	通过 URL 添加网页
twelvelabs_delete_kb_doc	永久删除文档

对话工具

工具	功能说明
twelvelabs_list_conversations	按 Agent、时间、成功状态、时长、评分、状态和标签筛选历史记录
twelvelabs_get_conversation	获取完整对话记录、音频／标签元数据、数据收集和评估结果
twelvelabs_rerun_conversation_analysis	使用当前 Agent 设置重新分析已完成的对话
twelvelabs_rerun_conversation_evaluation	重新运行已完成对话中的单项评估标准
twelvelabs_list_conversation_tags	列出工作区对话标签
twelvelabs_create_conversation_tag	创建工作区对话标签
twelvelabs_update_conversation_tag	重命名标签或更改其描述
twelvelabs_assign_conversation_tags	为对话应用一个或多个标签
twelvelabs_remove_conversation_tag	从对话中移除标签
twelvelabs_delete_conversation_tag	永久删除工作区对话标签

语音工具

工具	功能说明
twelvelabs_list_voices	浏览可用语音及其 ID 和标签

安全

• 输入验证 -- 所有工具参数都会在传给 API 前使用 Zod 模式进行验证
• 强制使用 HTTPS -- 会验证 Webhook URL，确保仅使用 HTTPS
• 路径遍历防护 -- 会清理文档和 Agent ID，以防止路径遍历
• 错误清理 -- 捕获内部错误并以安全的 MCP 错误响应形式返回；绝不会向客户端暴露原始堆栈跟踪

开发

npm run dev   # watch mode with tsx -- auto-reloads on file changes
npm run build # compile to dist/

贡献

1. Fork 此仓库
2. 创建功能分支（git checkout -b feat/my-feature）
3. 提交更改（git commit -m 'feat: add my feature'）
4. 推送到该分支（git push origin feat/my-feature）
5. 发起 Pull Request

许可证

MIT -- 详情请参阅 LICENSE。

架构说明

所有工具共用一个 Axios 客户端实例（src/client.ts），并在启动时通过 ELEVENLABS_API_KEY 进行初始化。工具实现位于 src/tools/ 中——每个领域对应一个 文件——并在 src/index.ts 中注册到 McpServer。服务器通过 stdio 传输（stdin/stdout）进行通信，因此所有调试日志都使用 console.error（stderr），而不是 console.log。