Kaltura Model Context Protocol (MCP) Server

Kaltura MCP 服务

一个 Model Context Protocol（MCP）服务，提供安全的只读工具来管理 Kaltura API 操作。此服务可让 AI 助手安全地搜索、发现和分析 Kaltura 媒体内容。

功能

• 媒体发现：通过高级筛选搜索和浏览媒体条目
• 内容分析：访问字幕、转录文本和附件内容
• 类别管理：浏览和探索内容类别
• 分析：获取观看分析数据和性能指标
• 安全访问：只读操作，并进行全面的输入验证
• 会话管理：自动管理会话，并支持配置过期时间

安装

1. 克隆此仓库：

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

2. 安装依赖项：

pip install -e .

使用模式

此服务支持两种部署模式：

🔧 本地 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：你的数字 Partner 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 账户中查找有关 [topic] 的视频”

本地设置故障排查

问题：找不到 kaltura-mcp 命令

• 解决方案：确保已使用 pip install kaltura-mcp 安装，并且该命令位于 PATH 中

问题：“Error: Missing required environment variables”

• 解决方案：
  1. 检查项目目录中是否存在 .env 文件
  2. 验证文件权限：ls -la .env（应显示 -rw-------）
  3. 确保 .env 文件中已设置所有必需的 Kaltura 凭据

问题：“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 的身份验证，用于安全管理凭据
• 基于 Web 的授权流程，便于用户进行设置
• 多租户支持，可作为服务托管

可用工具

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 - 体验质量（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. 输入凭据：用户通过网页表单安全地输入其 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. 用户引导

将用户发送到：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：用于衡量流媒体性能的体验质量（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