twelvelabs-mcp-server

TwelveLabs MCP サーバー

このプロジェクトは、動画理解プラットフォームの TwelveLabs とは関係ありません。 ElevenLabs の**ElevenLabs Conversational AI API**向けの MCP サーバーです。音声エージェント、ナレッジベース、会話、TTS を扱います。「TwelveLabs」という名称は、このプロジェクトのコードネームにすぎません。

互換性のあるあらゆる MCP クライアントから ElevenLabs Conversational AI API に直接アクセスできる、拡張版 MCP（Model Context Protocol）サーバーです。公式の ElevenLabs MCP コネクターでは公開されていない機能も利用できます。

対応機能

• エージェント -- 一覧表示、完全な設定の取得（LLM モデルと温度を含む）、プロンプトや設定の更新、ウェブフックやファイルアップロードの管理
• ナレッジベース -- 一覧表示、全コンテンツの読み取り、テキスト／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_1001kjbh14xce5kbreh55ydf4rae の完全な設定を取得して" "そのエージェントの直近 10 件の会話を表示して" "conversation_xyz の文字起こしと分析を取得して"

互換性

このサーバーは、stdio トランスポートに対応し、ローカルサーバープロセス用の環境変数を設定できる MCP クライアントで動作します。リモート HTTP MCP サーバーにしか対応していないクライアントには、互換性のある stdio ブリッジまたはプロキシが必要です。

ツールリファレンス

エージェントツール

ツール	機能
twelvelabs_list_agents	アカウント内のすべてのエージェントを一覧表示
twelvelabs_get_agent	完全な設定：LLM モデル、音声、ナレッジベースのドキュメント、ウェブフック、プロンプトのプレビュー
twelvelabs_get_agent_prompt	省略されていないシステムプロンプトの全文
twelvelabs_update_agent_prompt	システムプロンプトや最初のメッセージを置き換え
twelvelabs_update_agent_settings	温度、音声、TTS 設定、言語を変更
twelvelabs_update_agent_conversation_capabilities	チャットでのファイルアップロードを有効化し、最大時間のメッセージを設定
twelvelabs_list_agent_conversations	1 つのエージェントの最近の会話
twelvelabs_get_agent_webhook	現在のウェブフック URL
twelvelabs_set_agent_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	エージェント、時間、成功、所要時間、評価、ステータス、タグで履歴を絞り込みます
twelvelabs_get_conversation	トランスクリプト全体、音声／タグのメタデータ、データ収集、評価結果を取得します
twelvelabs_rerun_conversation_analysis	現在のエージェント設定を使用して、完了した会話を再分析します
twelvelabs_rerun_conversation_evaluation	完了した会話の単一の評価基準を再実行します
twelvelabs_list_conversation_tags	ワークスペースの会話タグを一覧表示します
twelvelabs_create_conversation_tag	ワークスペースの会話タグを作成します
twelvelabs_update_conversation_tag	タグの名前を変更するか、説明を変更します
twelvelabs_assign_conversation_tags	1 つ以上のタグを会話に適用します
twelvelabs_remove_conversation_tag	会話からタグを削除します
twelvelabs_delete_conversation_tag	ワークスペースの会話タグを完全に削除します

音声ツール

ツール	説明
twelvelabs_list_voices	ID とラベル付きで利用可能な音声を確認します

セキュリティ

• 入力検証 -- API に渡す前に、すべてのツールパラメーターを Zod スキーマで検証します
• HTTPS の強制 -- webhook URL が HTTPS のみを使用するよう検証します
• パストラバーサル対策 -- ドキュメント ID とエージェント ID をサニタイズし、パストラバーサルを防ぎます
• エラーのサニタイズ -- 内部エラーを捕捉し、安全な MCP エラーレスポンスとして返します。生のスタックトレースがクライアントに公開されることはありません

開発

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

コントリビューション

1. リポジトリをフォークします
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 を参照してください。

アーキテクチャに関する注記

すべてのツールは、起動時に ELEVENLABS_API_KEY を使って初期化される単一の Axios クライアントインスタンス（src/client.ts）を共有します。ツールの実装は src/tools/ にあり、ドメインごとに 1 つのファイルに分かれています。これらは src/index.ts で McpServer に登録されます。サーバーは stdio トランスポート（stdin/stdout）で通信するため、デバッグログにはすべて console.log ではなく console.error（stderr）を使用します。