TwelveLabs MCP Server

本项目与 TwelveLabs（视频理解平台）无关。 它是一个面向 ElevenLabs Conversational AI API 的 MCP 服务器 —— 涵盖语音代理、知识库、对话和 TTS。名称 "TwelveLabs" 仅为项目代号。

一个增强型 MCP（Model Context Protocol）服务器，让任何兼容的 MCP 客户端都能直接访问 ElevenLabs Conversational AI API —— 包括官方 ElevenLabs MCP 连接器未暴露的能力。

涵盖内容

• Agents（代理） -- 列出、获取完整配置（包括 LLM 模型 + 温度）、更新提示词/设置、管理 webhook 和文件上传

• Knowledge Base（知识库） -- 列出、读取完整内容、添加文本/URL 文档、删除文档

• Conversations（对话） -- 筛选和标记历史记录、查看转录文本、重新运行通话后分析/评估

• Voices（语音） -- 列出和搜索可用语音

Related MCP server: elevenlabs-mcp-experiments

前提条件

• Node.js >= 18

• ElevenLabs API key -- 在 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_1001kjbh14xce5kbreh55ydf4rae 的完整配置" "显示该代理最近 10 条对话" "获取 conversation_xyz 的转录文本和分析"

兼容性

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

工具参考

代理工具

知识库工具

对话工具

语音工具

安全性

• 输入验证 -- 所有工具参数在到达 API 之前都会使用 Zod 模式进行验证

• HTTPS 强制 -- webhook URL 被验证为仅使用 HTTPS

• 路径遍历保护 -- 文档和代理 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。