Kaltura MCP

MCP服务器

一种模型上下文协议（MCP）服务器，为管理Kaltura API操作提供安全的只读工具。该服务器使AI助手能够安全地搜索、发现和分析Kaltura媒体内容。

特性

• 媒体发现：使用高级过滤功能搜索和浏览媒体条目
• 内容分析：访问标题、成绩单和附件内容
• 品类管理：浏览和探索内容类别
• 分析：检索查看分析和性能指标
• 安全访问：具有全面输入验证的只读操作
• 会话管理：具有可配置到期时间的自动会话处理

安装

1. 克隆此存储库：

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

1. 安装依赖项：

pip install -e .

使用模式

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

🔧 本地MCP服务器（标准模式）

最适合： 个人使用，直接克劳德桌面集成，开发

🌐 远程MCP服务器（HTTP/SSE模式）

最适合： 托管服务、多用户、生产部署

______________________________________________________________________

本地MCP服务器设置（克劳德桌面）

步骤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. 生成a .env 具有适当权限的文件（600）
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)
• 合作伙伴ID：您的数字合作伙伴ID（在KMC中找到→ 设置→ 集成设置）
• 管理员密码：您的API管理员密钥（在KMC中找到→ 设置→ 集成设置）
• 用户ID：您的Kaltura用户ID（通常是您的电子邮件或 admin)

步骤4：配置Claude桌面

打开您的Claude Desktop配置文件：

macOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json 视窗: %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以使更改生效。

步骤6：测试集成

在Claude Desktop中，尝试询问：

• “搜索最近的Kaltura视频”
• “列出我的Kaltura类别”
• “在我的Kaltura帐户中查找有关\[主题\]的视频”

本地设置故障排除

问题: kaltura-mcp 命令未找到

• 解决方案：确保已安装 pip install kaltura-mcp 命令在您的PATH中

问题：“错误：缺少必需的环境变量”

• 解决方案:

1. 检查一下 .env 文件存在于您的项目目录中 1. 验证文件权限： ls -la .env （应显示 -rw-------) 1. 确保在中设置了所有必需的Kaltura凭据 .env 文件

问题：“凭据无效”或“身份验证失败”

• 解决方案:

1. 在Kaltura KMC中验证您的凭据→ 设置→ 集成设置 1. 检查 .env 文件中的拼写错误或多余空格 1. 跑 python setup_env.py 重新创建配置

问题：Claude Desktop未显示MCP服务器

• 解决方案:

1. 使用JSON验证器检查配置文件语法 1. 验证命令路径是否正确（使用 which kaltura-mcp) 1. 完全重新启动克劳德桌面 1. 检查Claude Desktop日志中的错误消息

问题：“找不到.env文件”错误

• 解决方案:

1. 跑 python setup_env.py 从您的项目目录 1. 确保 .env 文件与服务器代码位于同一目录中 1. 检查文件权限： 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

远程服务器提供：

• HTTP/SSE传输 用于MCP协议
• 基于JWT的身份验证 用于安全凭据管理
• 基于Web的授权 用户友好的设置流程
• 多租户支持 用于托管即服务

可用工具

1. get_media_entry -获取特定媒体条目的详细信息

- 参数：entry_id（必填）

1. 列表_类别 -列出和搜索内容类别

- 参数：search_text，限制

1. 分析工具 -具有目标驱动功能的综合分析套件：

- get_analytics -用于报告和分析的一般分析数据 - get_analytics_timeseries -针对图表优化的时间序列数据 - get_video_retention -整个视频中详细的观众保留率分析 - 获取高度信息 -实时分析每约30秒更新一次 - get_quality_metrics -体验质量（QoE）和流媒体性能 - 获取地理信息_分解 -不同粒度的基于位置的分析 - 列表_分析_功能 -发现所有可用的分析功能 - 看 分析指南 详细用法

1. get_download_url -获取媒体文件的直接下载URL

- 参数：entry_id（必填），flavor_id

1. get_thubnail_url -获取具有自定义尺寸的视频缩略图/预览图像URL

- 参数：entry_id（必填）、宽度、高度、秒

1. search_entrys -通过智能排序和过滤搜索和发现媒体条目

- 参数：query（必填）、search_type、match_type、specific_field、boolean_operator、include_hlights、custom_metadata、date_range、max_results、sort_field、sort_order

1. list_caption_assets -列出媒体条目的可用字幕和字幕

- 参数：entry_id（必填）

1. get_caption_content -获取字幕/副标题内容并下载URL

- 参数：caption_asset_id（必填）

1. 列表_附件_资产 -列出媒体条目的附件资产

- 参数：entry_id（必填）

1. 获取附件内容 -获取附件内容详细信息并下载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")

1. 内容_范围 -用于查找媒体的自然语言搜索助手

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

1. 可访问性_审计 -内容可访问性合规性检查器

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

1. 保留分析 -创建全面的留存分析报告

   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分钟

1. kaltura://categories/tree -具有条目计数的类别层次结构

- 完整的类别树结构 - 每个类别的条目计数 - 亲子关系 - 缓存30分钟

1. kaltura://media/recent/｛计数｝ -最近的媒体报道

- 将{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一起使用的最简单方法是通过代理客户端：

{
  "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：详细的观众留存曲线，显示观众流失的确切位置
• 获取高度信息：实时分析每约30秒更新一次，用于监控
• get_quality_metrics：流媒体性能的体验质量（QoE）指标
• 获取地理信息_分解：国家、地区或城市层面的基于位置的分析

分析能力：

• 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服务器在范围有限的隔离进程中运行
• ✅ 无网络暴露 -API与Kaltura直接沟通
• ✅ 本地凭据存储 -凭据永远不会离开您的计算机
• ✅ 安全传输 -安全传递给MCP服务器进程的凭据

远程模式安全

• ✅ 凭证加密 -JWT令牌加密的Kaltura凭据
• ✅ 令牌过期 -自动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文档 -API官方文件

发展

运行测试

pytest

代码格式化

black src/
ruff check src/

许可证

麻省理工学院