Kaltura Model Context Protocol (MCP) Server

Kaltura MCP サーバー

Kaltura API の操作を管理するための、安全な読み取り専用ツールを提供する Model Context Protocol（MCP）サーバーです。このサーバーを使用すると、AI アシスタントが Kaltura のメディアコンテンツを安全に検索、探索、分析できます。

特長

• メディアの検索：高度なフィルタリングを使ってメディアエントリーを検索、閲覧できます
• コンテンツ分析：字幕、文字起こし、添付ファイルのコンテンツにアクセスできます
• カテゴリ管理：コンテンツカテゴリを閲覧、探索できます
• 分析：視聴分析とパフォーマンス指標を取得できます
• 安全なアクセス：包括的な入力検証を備えた読み取り専用操作
• セッション管理：有効期限を設定できる自動セッション処理

インストール

1. このリポジトリをクローンします：

git clone https://github.com/zoharbabin/kaltura-mcp.git
cd kaltura-mcp

2. 依存関係をインストールします：

pip install -e .

使用モード

このサーバーは、次の 2 つのデプロイモードに対応しています：

🔧 ローカル MCP サーバー（Stdio モード）

最適な用途： 個人利用、Claude Desktop との直接連携、開発

🌐 リモート MCP サーバー（HTTP/SSE モード）

最適な用途： ホスト型サービス、複数ユーザー、本番環境へのデプロイ

---

ローカル MCP サーバーのセットアップ（Claude Desktop）

ステップ 1：パッケージをインストールする

pip install kaltura-mcp

ステップ 2：環境設定をセットアップする

🔒 安全な方法（推奨）：対話型セットアップスクリプトを使用します：

# Navigate to your project directory
cd /path/to/kaltura-mcp

# Run the interactive setup
python setup_env.py

スクリプトの案内に沿って、次の操作を行います：

1. stdio（ローカル）モードとリモートモードのどちらかを選択する
2. Kaltura の認証情報を安全に入力する
3. 適切なアクセス権（600）を設定した .env ファイルを生成する
4. Claude Desktop の設定を正確に提示する

📋 手動で行う方法：サンプルファイルをコピーして編集します：

# Copy the example file
cp .env.example .env

# Edit with your credentials
# - For stdio mode: Only fill in KALTURA_* variables
# - For remote mode: Fill in JWT_SECRET_KEY, OAUTH_*, and SERVER_* variables
nano .env

# Set secure permissions
chmod 600 .env

ステップ 3：Kaltura の認証情報を取得する

Kaltura アカウントから、次の認証情報を取得する必要があります：

• サービス URL：Kaltura サーバーの URL（通常は https://cdnapisec.kaltura.com）
• Partner ID：数値形式のパートナー ID（KMC → Settings → Integration Settings にあります）
• Admin Secret：API 管理者用のシークレットキー（KMC → Settings → Integration Settings にあります）
• User ID：Kaltura のユーザー ID（通常はメールアドレスまたは admin）

ステップ 4：Claude Desktop を設定する

Claude Desktop の設定ファイルを開きます：

macOS：~/Library/Application\ Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json

🔒 安全な設定（認証情報は .env ファイルに保存）：

{
  "mcpServers": {
    "kaltura": {
      "command": "/full/path/to/kaltura-mcp"
    }
  }
}

重要な注意事項：

• /full/path/to/kaltura-mcp を、実際の kaltura-mcp コマンドのパスに置き換えてください（which kaltura-mcp で確認できます）
• サーバーはプロジェクトディレクトリから .env ファイルを自動的に読み込みます
• setup_env.py スクリプトはコマンドの正しいパスを自動的に検出して提示します

ステップ 5：Claude Desktop を再起動する

設定ファイルを保存したら、変更を反映するために Claude Desktop を完全に再起動してください。

ステップ 6：連携をテストする

Claude Desktop で、次のように質問してみてください：

• 「最近の Kaltura 動画を検索して」
• 「Kaltura のカテゴリを一覧表示して」
• 「Kaltura アカウントから、[トピック] に関する動画を探して」

ローカルセットアップのトラブルシューティング

問題：kaltura-mcp コマンドが見つかりません

• 解決策：pip install kaltura-mcp でインストールしたこと、およびコマンドが PATH に含まれていることを確認してください。

問題：「Error: Missing required environment variables」

• 解決策：
  1. プロジェクトディレクトリに .env ファイルがあることを確認してください。
  2. ファイルのアクセス権を確認します：ls -la .env（-rw------- と表示されるはずです）
  3. 必要な Kaltura の認証情報がすべて .env ファイルに設定されていることを確認してください。

問題：「Invalid credentials」または「Authentication failed」

• 解決策：
  1. Kaltura KMC → Settings → Integration Settings で認証情報を確認してください。
  2. .env ファイルに誤字や余分なスペースがないか確認してください。
  3. python setup_env.py を実行して設定を再作成してください。

問題：Claude Desktop に MCP サーバーが表示されません

• 解決策：
  1. JSON バリデーターで設定ファイルの構文を確認してください。
  2. コマンドのパスが正しいことを確認します（which kaltura-mcp を使用してください）。
  3. Claude Desktop を完全に再起動してください。
  4. Claude Desktop のログでエラーメッセージを確認してください。

問題：「.env file not found」エラー

• 解決策：
  1. プロジェクトディレクトリで python setup_env.py を実行してください。
  2. .env ファイルがサーバーコードと同じディレクトリにあることを確認してください。
  3. ファイルのアクセス権を確認します：ls -la .env（-rw------- と表示されるはずです）

✅ セキュリティ上のメリット：

• ✅ 安全なファイルアクセス権（600：所有者のみ）
• ✅ デフォルトで Git の追跡対象外（コミットされません）
• ✅ プロジェクトディレクトリ内に配置（管理が簡単です）
• ✅ 標準的な .env のパターン（開発者にとってなじみがあります）
• ✅ 設定ファイルに認証情報を含めない（セキュリティが向上します）

---

リモート MCP サーバーのセットアップ

設定

リモート／ホスト型のデプロイでは、追加の環境変数が必要です：

cp .env.example .env
# Configure remote server settings

必須の環境変数：

• JWT_SECRET_KEY：JWT トークンの署名に使用する強力なシークレットキー（⚠️ セキュリティ上、非常に重要です）
• OAUTH_REDIRECT_URI：OAuth コールバック URL（例：https://your-domain.com/oauth/callback）
• SERVER_HOST：サーバーのバインドアドレス（デフォルト：0.0.0.0）
• SERVER_PORT：サーバーのポート（デフォルト：8000）

任意の環境変数：

• SERVER_RELOAD：開発時の自動リロードを有効にします（デフォルト：false）
• OAUTH_CLIENT_ID：カスタム OAuth クライアント ID
• OAUTH_CLIENT_SECRET：カスタム OAuth クライアントシークレット

リモートサーバーの実行

# Using the installed command
kaltura-mcp-remote

# Or using Python module
python -m kaltura_mcp.remote_server

リモートサーバーは以下を提供します：

• MCP プロトコル用の HTTP/SSE トランスポート
• 認証情報を安全に管理するための JWT ベースの認証
• ユーザーが使いやすいセットアップを実現するウェブベースの認可フロー
• サービスとしてホスティングするためのマルチテナント対応

利用可能なツール

1. get_media_entry - 特定のメディアエントリーの詳細情報を取得します

   • パラメーター：entry_id（必須）

2. list_categories - コンテンツカテゴリを一覧表示して検索します

   • パラメーター：search_text、limit

3. Analytics Tools - 用途に応じた関数を備えた包括的な分析スイートです：

   • get_analytics - レポートと分析用の一般的な分析データ
   • get_analytics_timeseries - グラフに最適化された時系列データ
   • get_video_retention - 動画全体にわたる詳細な視聴者維持率分析
   • get_realtime_metrics - 約30秒ごとに更新されるライブ分析データ
   • get_quality_metrics - Quality of Experience（QoE）とストリーミングのパフォーマンス
   • get_geographic_breakdown - さまざまな粒度での位置情報ベースの分析
   • list_analytics_capabilities - 利用可能なすべての分析機能を確認します
   • 詳細な使い方については、Analytics Guideをご覧ください

4. get_download_url - メディアファイルの直接ダウンロードURLを取得します

   • パラメーター：entry_id（必須）、flavor_id

5. get_thumbnail_url - カスタムサイズの動画サムネイル／プレビュー画像URLを取得します

   • パラメーター：entry_id（必須）、width、height、second

6. search_entries - インテリジェントな並べ替えとフィルタリングでメディアエントリーを検索し、見つけます

   • パラメーター：query（必須）、search_type、match_type、specific_field、boolean_operator、include_highlights、custom_metadata、date_range、max_results、sort_field、sort_order

7. list_caption_assets - メディアエントリーで利用可能なキャプションと字幕を一覧表示します

   • パラメーター：entry_id（必須）

8. get_caption_content - キャプション／字幕の内容とダウンロードURLを取得します

   • パラメーター：caption_asset_id（必須）

9. list_attachment_assets - メディアエントリーの添付ファイルアセットを一覧表示します

   • パラメーター：entry_id（必須）

10. get_attachment_content - 添付ファイルの詳細を取得し、内容をbase64形式でダウンロードします

    • パラメーター：attachment_asset_id（必須）

プロンプト

サーバーは、複雑なワークフローをユーザーが進められるよう、インテリジェントなプロンプトを提供します：

1. analytics_wizard - 包括的な分析レポートを作成するための対話型ガイド

   Arguments:
   - analysis_goal: What to analyze (e.g., "video performance", "viewer engagement", "geographic reach")
   - time_period: Time range (e.g., "today", "yesterday", "last_week", "last_month")
   

2. content_discovery - メディアを見つけるための自然言語検索アシスタント

   Arguments:
   - search_intent: What you're looking for in natural language
   - include_details: Whether to fetch captions/attachments (yes/no)
   

3. accessibility_audit - コンテンツのアクセシビリティ準拠を確認します

   Arguments:
   - audit_scope: What to audit ("all", "recent", "category:name", or entry_id)
   

4. retention_analysis - 包括的な視聴者維持率分析レポートを作成します

   Arguments:
   - entry_id: Video to analyze (e.g., "1_3atosphg") [required]
   - time_period: Months of data to analyze (default: "12")
   - output_format: "interactive" (HTML) or "markdown" (default: "interactive")
   

リソース

サーバーは、よく使われるデータをキャッシュ済みリソースとして公開します：

1. kaltura://analytics/capabilities - 分析機能に関する完全なドキュメント

   • 60種類以上のレポートタイプと説明
   • 利用可能な指標とディメンション
   • さまざまなユースケースに応じたベストプラクティス
   • 30分間キャッシュされます

2. kaltura://categories/tree - エントリー数を含むカテゴリ階層

   • 完全なカテゴリツリー構造
   • カテゴリごとのエントリー数
   • 親子関係
   • 30分間キャッシュされます

3. kaltura://media/recent/{count} - 最近のメディアエントリー

   • {count}をエントリー数に置き換えます（例：kaltura://media/recent/20）
   • 最大100件
   • 基本的なメタデータを含みます
   • 5分間キャッシュされます

---

リモートMCPサーバー（高度な設定）

ユーザー認証フロー

1. サーバーのデプロイ：リモートサーバーをホスティング環境にデプロイします
2. ユーザー認証：ユーザーがhttps://your-server.com/oauth/authorizeにアクセスします
3. 認証情報の入力：ユーザーがWebフォームからKalturaの認証情報を安全に入力します
4. トークンの生成：サーバーが暗号化された認証情報を含むJWTトークンを生成します
5. クライアントの設定：ユーザーがサーバーURLとトークンをMCPクライアントに追加します

リモート設定の手順

1. 安全なJWTシークレットを生成する

# Generate a strong secret key
python -c "import secrets; print(secrets.token_urlsafe(32))"

2. 環境を設定する

# Set in your .env file or environment
JWT_SECRET_KEY=your-generated-secret-key-here
OAUTH_REDIRECT_URI=https://your-domain.com/oauth/callback
SERVER_HOST=0.0.0.0
SERVER_PORT=8000

3. サーバーをデプロイする

オプションA：直接Pythonで実行

kaltura-mcp-remote

オプションB：Docker

docker-compose up -d

オプションC：Gunicornを使った本番環境（任意）

# Install gunicorn separately if needed for production
pip install gunicorn
gunicorn -w 4 -k uvicorn.workers.UvicornWorker kaltura_mcp.remote_server:app

4. ユーザーのオンボーディング

ユーザーを次の URL に誘導します：https://your-server.com/oauth/authorize?response_type=code&client_id=kaltura-mcp&redirect_uri=https://your-server.com/oauth/callback&state=user123

5. クライアントの設定

Claude Desktop の場合（リモートモード）：

Claude Desktop でリモートサーバーを使う最も簡単な方法は、プロキシクライアントを利用することです。

{
  "mcpServers": {
    "kaltura-remote": {
      "command": "kaltura-mcp-proxy",
      "env": {
        "KALTURA_REMOTE_SERVER_URL": "https://your-server.com/mcp/messages",
        "KALTURA_REMOTE_ACCESS_TOKEN": "your-jwt-token-from-authorization-flow"
      }
    }
  }
}

プロキシクライアント（kaltura-mcp-proxy）は、リモートサーバーにリクエストを転送するローカルの stdio MCP サーバーとして機能します。これにより、Claude Desktop との互換性が最も高くなります。

カスタム MCP クライアントの場合：

// HTTP transport with authentication
const transport = new HTTPTransport({
  baseUrl: "https://your-server.com/mcp/messages",
  headers: {
    "Authorization": "Bearer user-jwt-token-here"
  }
});

アナリティクスのドキュメント

MCP サーバーは、さまざまな用途に合わせて最適化された、目的別の関数を備えた包括的なアナリティクス機能を提供します。

目的に特化したアナリティクス関数：

• get_analytics：詳細な分析に使える、テーブル形式の包括的なレポートデータ
• get_analytics_timeseries：チャートや可視化に最適化された時系列データ
• get_video_retention：視聴者が離脱した箇所を正確に示す、詳細な視聴者維持率曲線
• get_realtime_metrics：モニタリング用に約 30 秒ごとに更新されるリアルタイムのアナリティクス
• get_quality_metrics：ストリーミング性能に関する Quality of Experience（QoE）指標
• get_geographic_breakdown：国、地域、市区町村レベルの位置情報に基づくアナリティクス

アナリティクス機能：

• コンテンツ、ユーザー、地域、プラットフォームなどを対象とする 60 種類以上のレポート
• カスタム分析や可視化に使える生データへのアクセス
• 離脱ポイントやエンゲージメントのパターンなど、インテリジェントなインサイト
• 日付範囲、カテゴリ、ユーザー、ディメンションによるフィルタリングに対応

詳しいドキュメントについては、次を参照してください。

• アナリティクスガイド - すべてのアナリティクス関数を網羅したリファレンス
• アナリティクスの例 - コード例と可視化

セキュリティに関する考慮事項

本番環境へのデプロイ

• HTTPS の使用：TLS/SSL 証明書を使って必ずデプロイしてください
• JWT シークレットの保護：暗号学的に十分な強度を持つシークレットキー（32 バイト以上）を使用してください
• 環境のセキュリティ：シークレットをバージョン管理にコミットしないでください
• ネットワークのセキュリティ：必要に応じてファイアウォールや VPN アクセスを使用してください
• 定期的な更新：セキュリティパッチを適用するため、依存関係を最新の状態に保ってください

JWT トークンのセキュリティ

• トークンの有効期限：トークンはデフォルトで 24 時間後に有効期限が切れます
• 認証情報の暗号化：Kaltura の認証情報は JWT ペイロード内で暗号化されます
• スコープの制限：トークンで許可されるのは、読み取り専用の Kaltura 操作のみです
• 失効：サーバーを再起動すると、既存のすべてのトークンが無効になります

インフラストラクチャ

# Example nginx configuration for production
server {
    listen 443 ssl;
    server_name your-kaltura-mcp.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location / {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Docker によるデプロイ

本番環境用の docker-compose.yml：

version: '3.8'
services:
  kaltura-mcp:
    build: .
    ports:
      - "8000:8000"
    environment:
      - JWT_SECRET_KEY=${JWT_SECRET_KEY}
      - OAUTH_REDIRECT_URI=https://your-domain.com/oauth/callback
      - SERVER_HOST=0.0.0.0
      - SERVER_PORT=8000
    restart: unless-stopped
    volumes:
      - ./logs:/app/logs
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.kaltura-mcp.rule=Host(\`your-domain.com\`)"
      - "traefik.http.routers.kaltura-mcp.tls=true"

モニタリングとログ記録

リモートサーバーにはログ記録機能が組み込まれており、次の方法でモニタリングできます。

• ヘルスチェック：GET / を呼び出すと、サーバーの状態が返されます
• メトリクス：Docker ボリュームまたはサーバーログからアクセスログを確認できます
• エラー追跡：外部のエラー追跡サービスを設定してください

重要なセキュリティ上の注意事項

ローカルモードのセキュリティ（推奨）

• ✅ 直接設定 - 認証情報は Claude Desktop で直接設定します
• ✅ MCP 標準への準拠 - クライアントが環境変数を通じて認証情報をサーバーに渡します
• ✅ プロセスの分離 - MCP サーバーは、スコープを制限した分離プロセスで実行されます
• ✅ ネットワークに公開されない - Kaltura API と直接通信します
• ✅ ローカルでの認証情報の保存 - 認証情報がマシンの外部に送信されることはありません
• ✅ 安全な送信 - 認証情報は MCP サーバープロセスに安全に渡されます

リモートモードのセキュリティ

• ✅ 認証情報の暗号化 - Kaltura の認証情報は JWT トークン内で暗号化されます
• ✅ トークンの有効期限 - トークンは 24 時間後に自動的に期限切れになります
• ✅ TLS 暗号化 - 本番環境では HTTPS が必須です
• ⚠️ サーバーの信頼性 - リモートサーバーの運用者を信頼する必要があります
• ⚠️ 認証情報の送信 - 認証情報はリモートサーバーに送信されます（暗号化済み）

本番環境チェックリスト

• 有効な証明書を使用した HTTPS を使用します
• 強力な JWT シークレットキーを生成します（32 バイト以上）
• 安全な環境変数を設定します
• 適切なロギングと監視を設定します
• レート制限を実装します（nginx/cloudflare）
• セキュリティ更新を定期的に適用します
• バックアップと災害復旧計画を用意します

デプロイアーキテクチャ

個人利用（推奨）

Claude Desktop ←→ Local MCP Server ←→ Kaltura API

小規模チーム

Claude Desktop ←→ Proxy Client ←→ Remote MCP Server ←→ Kaltura API

エンタープライズ

Multiple Clients ←→ Load Balancer ←→ Multiple MCP Servers ←→ Kaltura API
                                          ↓
                                    Redis/Database

ドキュメント

• アナリティクスガイド - アナリティクス機能の包括的なガイド
• プロンプトとリソース - MCP のプロンプトとリソースに関する詳細なドキュメント
• API ドキュメント - Kaltura 公式 API ドキュメント

開発

テストの実行

pytest

コードのフォーマット

black src/
ruff check src/

ライセンス

MIT