Kaltura MCP Server

Un servidor para realizar operaciones seguras y de solo lectura en la API de Kaltura.

Documentación

Servidor MCP de Kaltura

Un servidor de Model Context Protocol (MCP) que proporciona herramientas seguras y de solo lectura para gestionar operaciones de la API de Kaltura. Este servidor permite a los asistentes de IA buscar, descubrir y analizar contenido multimedia de Kaltura de forma segura.

Características

Descubrimiento de medios: Busca y navega por entradas multimedia con filtrado avanzado
Análisis de contenido: Accede a subtítulos, transcripciones y contenido de archivos adjuntos
Gestión de categorías: Navega y explora categorías de contenido
Analíticas: Recupera analíticas de visualización y métricas de rendimiento
Acceso seguro: Operaciones de solo lectura con validación integral de entrada
Gestión de sesiones: Manejo automático de sesiones con caducidad configurable

Instalación

Clona este repositorio:

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

Instala las dependencias:

pip install -e .

Modos de uso

Este servidor admite dos modos de implementación:

🔧 Servidor MCP local (modo Stdio)

Ideal para: Uso personal, integración directa con Claude Desktop, desarrollo

🌐 Servidor MCP remoto (modo HTTP/SSE)

Ideal para: Servicios alojados, múltiples usuarios, implementaciones de producción

Configuración del servidor MCP local (Claude Desktop)

Paso 1: Instala el paquete

pip install kaltura-mcp

Paso 2: Configura las variables de entorno

🔒 Método seguro (recomendado): Usa el script de configuración interactivo:

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

# Run the interactive setup
python setup_env.py

El script te guiará a través de:

Elegir entre modo stdio (local) o remoto
Ingresar de forma segura tus credenciales de Kaltura
Generar un archivo .env con permisos adecuados (600)
Proporcionar la configuración exacta de Claude Desktop

📋 Método manual: Copia y edita el archivo de ejemplo:

# 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

Paso 3: Obtén tus credenciales de Kaltura

Necesitarás estas credenciales de tu cuenta de Kaltura:

URL del servicio: La URL de tu servidor Kaltura (generalmente https://cdnapisec.kaltura.com)
ID de socio: Tu ID de socio numérico (se encuentra en KMC → Configuración → Configuración de integración)
Secreto de administrador: Tu clave secreta de administrador de API (se encuentra en KMC → Configuración → Configuración de integración)
ID de usuario: Tu ID de usuario de Kaltura (generalmente tu correo electrónico o admin)

Paso 4: Configura Claude Desktop

Abre tu archivo de configuración de Claude Desktop:

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

🔒 Configuración segura (credenciales en archivo .env):

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

Notas importantes:

Reemplaza /full/path/to/kaltura-mcp con la ruta real a tu comando kaltura-mcp (encuéntrala con which kaltura-mcp)
El archivo .env se carga automáticamente desde el directorio del proyecto por el servidor
El script setup_env.py detectará y proporcionará automáticamente la ruta correcta del comando

Paso 5: Reinicia Claude Desktop

Después de guardar el archivo de configuración, reinicia Claude Desktop por completo para que los cambios surtan efecto.

Paso 6: Prueba la integración

En Claude Desktop, intenta preguntar:

"Busca videos recientes de Kaltura"
"Lista mis categorías de Kaltura"
"Encuentra videos sobre [tema] en mi cuenta de Kaltura"

Solución de problemas de configuración local

Problema: Comando kaltura-mcp no encontrado

Solución: Asegúrate de haber instalado con pip install kaltura-mcp y que el comando esté en tu PATH

Problema: "Error: Faltan variables de entorno requeridas"

Solución:
1. Verifica que el archivo .env exista en tu directorio de proyecto
2. Verifica los permisos del archivo: ls -la .env (debe mostrar -rw-------)
3. Asegúrate de que todas las credenciales requeridas de Kaltura estén configuradas en el archivo .env

Problema: "Credenciales inválidas" o "Autenticación fallida"

Solución:
1. Verifica tus credenciales en KMC de Kaltura → Configuración → Configuración de integración
2. Revisa el archivo .env por errores tipográficos o espacios adicionales
3. Ejecuta python setup_env.py para recrear la configuración

Problema: Claude Desktop no muestra el servidor MCP

Solución:
1. Verifica la sintaxis del archivo de configuración con un validador JSON
2. Verifica que la ruta del comando sea correcta (usa which kaltura-mcp)
3. Reinicia Claude Desktop por completo
4. Revisa los registros de Claude Desktop para ver mensajes de error

Problema: Error de "archivo .env no encontrado"

Solución:
1. Ejecuta python setup_env.py desde tu directorio de proyecto
2. Asegúrate de que el archivo .env exista en el mismo directorio que el código del servidor
3. Verifica los permisos del archivo: ls -la .env (debe mostrar -rw-------)

✅ Beneficios de seguridad:

✅ Permisos de archivo seguros (600 - solo propietario)
✅ Ignorado por Git por defecto (no se confirmará)
✅ Local al directorio del proyecto (fácil de gestionar)
✅ Patrón .env estándar (familiar para desarrolladores)
✅ Sin credenciales en archivos de configuración (seguridad mejorada)

Configuración del servidor MCP remoto

Configuración

Para implementación remota/alojada, se requieren variables de entorno adicionales:

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

Variables de entorno requeridas:

JWT_SECRET_KEY: Clave secreta fuerte para la firma de tokens JWT (⚠️ CRÍTICO PARA LA SEGURIDAD)
OAUTH_REDIRECT_URI: URL de devolución de llamada OAuth (por ejemplo, https://your-domain.com/oauth/callback)
SERVER_HOST: Dirección de enlace del servidor (predeterminado: 0.0.0.0)
SERVER_PORT: Puerto del servidor (predeterminado: 8000)

Variables de entorno opcionales:

SERVER_RELOAD: Habilita la recarga automática en desarrollo (predeterminado: false)
OAUTH_CLIENT_ID: ID de cliente OAuth personalizado
OAUTH_CLIENT_SECRET: Secreto de cliente OAuth personalizado

Ejecución del servidor remoto

# Using the installed command
kaltura-mcp-remote

# Or using Python module
python -m kaltura_mcp.remote_server

El servidor remoto proporciona:

Transporte HTTP/SSE para el protocolo MCP
Autenticación basada en JWT para la gestión segura de credenciales
Flujo de autorización basado en web para una configuración amigable
Soporte multiinquilino para alojamiento como servicio

Herramientas disponibles

get_media_entry - Obtén información detallada sobre una entrada multimedia específica
- Parámetros: entry_id (requerido)
list_categories - Lista y busca categorías de contenido
- Parámetros: search_text, limit
Herramientas de analíticas - Suite integral de analíticas con funciones específicas:
- get_analytics - Datos generales de analíticas para informes y análisis
- get_analytics_timeseries - Datos de series temporales optimizados para gráficos
- get_video_retention - Análisis detallado de retención de espectadores a lo largo de los videos
- get_realtime_metrics - Analíticas en vivo actualizadas cada ~30 segundos
- get_quality_metrics - Calidad de experiencia (QoE) y rendimiento de transmisión
- get_geographic_breakdown - Analíticas basadas en ubicación a varias granularidades
- list_analytics_capabilities - Descubre todas las funciones de analíticas disponibles
- Consulta la Guía de analíticas para uso detallado
get_download_url - Obtén la URL de descarga directa para archivos multimedia
- Parámetros: entry_id (requerido), flavor_id
get_thumbnail_url - Obtén la URL de la miniatura/imagen de vista previa del video con dimensiones personalizadas
- Parámetros: entry_id (requerido), width, height, second
search_entries - Busca y descubre entradas multimedia con ordenación y filtrado inteligente
- Parámetros: query (requerido), search_type, match_type, specific_field, boolean_operator, include_highlights, custom_metadata, date_range, max_results, sort_field, sort_order
list_caption_assets - Lista los subtítulos y leyendas disponibles para una entrada multimedia
- Parámetros: entry_id (requerido)
get_caption_content - Obtén el contenido de subtítulos/leyendas y la URL de descarga
- Parámetros: caption_asset_id (requerido)
list_attachment_assets - Lista los archivos adjuntos de una entrada multimedia
- Parámetros: entry_id (requerido)
get_attachment_content - Obtén los detalles del contenido adjunto y descarga el contenido como base64
- Parámetros: attachment_asset_id (requerido)

Prompts

El servidor proporciona prompts inteligentes para guiar a los usuarios a través de flujos de trabajo complejos:

analytics_wizard - Guía interactiva para crear informes de analíticas integrales

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")

content_discovery - Asistente de búsqueda en lenguaje natural para encontrar medios

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

accessibility_audit - Verificador de cumplimiento de accesibilidad de contenido

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

retention_analysis - Crea un informe integral de análisis de retención

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")

Recursos

El servidor expone datos de uso frecuente como recursos en caché:

kaltura://analytics/capabilities - Documentación completa de analíticas
- Los 60+ tipos de informes con descripciones
- Métricas y dimensiones disponibles
- Mejores prácticas para diferentes casos de uso
- En caché durante 30 minutos
kaltura://categories/tree - Jerarquía de categorías con recuentos de entradas
- Estructura completa del árbol de categorías
- Recuentos de entradas por categoría
- Relaciones padre-hijo
- En caché durante 30 minutos
kaltura://media/recent/{count} - Entradas multimedia recientes
- Reemplaza {count} con el número de entradas (por ejemplo, kaltura://media/recent/20)
- Máximo 100 entradas
- Incluye metadatos básicos
- En caché durante 5 minutos

Servidor MCP remoto (avanzado)

Flujo de autorización de usuario

Implementación del servidor: Implementa el servidor remoto en tu entorno de alojamiento
Autorización del usuario: Los usuarios visitan https://your-server.com/oauth/authorize
Ingreso de credenciales: Los usuarios ingresan de forma segura sus credenciales de Kaltura mediante un formulario web
Generación de tokens: El servidor genera un token JWT con credenciales cifradas
Configuración del cliente: Los usuarios agregan la URL del servidor y el token a su cliente MCP

Configuración remota paso a paso

1. Genera un secreto JWT seguro

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

2. Configura el entorno

# 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. Implementa el servidor

Opción A: Python directo

kaltura-mcp-remote

Opción B: Docker

docker-compose up -d

Opción C: Producción con Gunicorn (opcional)

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

4. Incorporación de usuarios

Envía a los usuarios a: https://your-server.com/oauth/authorize?response_type=code&client_id=kaltura-mcp&redirect_uri=https://your-server.com/oauth/callback&state=user123

5. Configuración del cliente

Para Claude Desktop (modo remoto):

La forma más fácil de usar el servidor remoto con Claude Desktop es mediante el cliente proxy:

{
  "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"
      }
    }
  }
}

El cliente proxy (kaltura-mcp-proxy) actúa como un servidor MCP stdio local que reenvía solicitudes a tu servidor remoto. Esto proporciona la mejor compatibilidad con Claude Desktop.

Para clientes MCP personalizados:

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

Documentación de analíticas

El servidor MCP proporciona una suite integral de analíticas con funciones específicas optimizadas para diferentes casos de uso:

Funciones de analíticas específicas:

get_analytics: Datos integrales de informes en formato de tabla para análisis detallado
get_analytics_timeseries: Datos de series temporales optimizados para gráficos y visualizaciones
get_video_retention: Curvas detalladas de retención de espectadores que muestran exactamente dónde abandonan los espectadores
get_realtime_metrics: Analíticas en vivo actualizadas cada ~30 segundos para monitoreo
get_quality_metrics: Métricas de calidad de experiencia (QoE) para rendimiento de transmisión
get_geographic_breakdown: Analíticas basadas en ubicación a nivel de país, región o ciudad

Capacidades de analíticas:

60+ tipos de informes que cubren contenido, usuarios, geografía, plataformas y más
Acceso a datos sin procesar para análisis y visualización personalizados
Información inteligente que incluye puntos de abandono y patrones de participación
Soporte para filtrar por rangos de fechas, categorías, usuarios y dimensiones

Para documentación integral, consulta:

Guía de analíticas - Referencia completa para todas las funciones de analíticas
Ejemplos de analíticas - Ejemplos de código y visualizaciones

Consideraciones de seguridad

Implementación en producción

Usa HTTPS: Implementa siempre con certificados TLS/SSL
Secreto JWT seguro: Usa una clave secreta criptográficamente fuerte (32+ bytes)
Seguridad del entorno: Nunca confirmes secretos en el control de versiones
Seguridad de red: Usa firewalls y acceso VPN cuando sea apropiado
Actualizaciones regulares: Mantén las dependencias actualizadas para parches de seguridad

Seguridad de tokens JWT

Caducidad de tokens: Los tokens caducan después de 24 horas por defecto
Cifrado de credenciales: Las credenciales de Kaltura se cifran dentro de la carga útil del JWT
Limitación de alcance: Los tokens se limitan a operaciones de solo lectura de Kaltura
Revocación: Reinicia el servidor para invalidar todos los tokens existentes

Infraestructura

# 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;
    }
}

Implementación con Docker

docker-compose.yml para producción:

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"

Monitoreo y Registro

El servidor remoto proporciona registro integrado y puede ser monitoreado mediante:

Verificación de salud: GET / devuelve el estado del servidor
Métricas: Acceda a los registros a través de volúmenes de Docker o registros del servidor
Seguimiento de errores: Configure servicios externos de seguimiento de errores

Notas de Seguridad Importantes

Seguridad en Modo Local (Recomendado)

✅ Configuración Directa - Credenciales configuradas directamente en Claude Desktop
✅ Cumplimiento de Estándares MCP - El cliente pasa las credenciales al servidor mediante variables de entorno
✅ Aislamiento de Procesos - El servidor MCP se ejecuta en un proceso aislado con alcance limitado
✅ Sin exposición a la red - Comunicación directa con la API de Kaltura
✅ Almacenamiento local de credenciales - Las credenciales nunca salen de su máquina
✅ Transmisión segura - Las credenciales se pasan de forma segura al proceso del servidor MCP

Seguridad en Modo Remoto

✅ Cifrado de credenciales - Las credenciales de Kaltura se cifran en tokens JWT
✅ Expiración de tokens - Expiración automática de tokens a las 24 horas
✅ Cifrado TLS - HTTPS requerido para producción
⚠️ Confianza en el servidor - Debe confiar en el operador del servidor remoto
⚠️ Transmisión de credenciales - Las credenciales se envían al servidor remoto (cifradas)

Lista de Verificación de Producción

Usar HTTPS con certificados válidos
Generar una clave secreta JWT fuerte (32+ bytes)
Configurar variables de entorno seguras
Establecer registro y monitoreo adecuados
Implementar limitación de velocidad (nginx/cloudflare)
Actualizaciones de seguridad periódicas
Plan de respaldo y recuperación ante desastres

Arquitecturas de Despliegue

Uso Personal (Recomendado)

Claude Desktop ←→ Local MCP Server ←→ Kaltura API

Equipo Pequeño

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

Empresa

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

Documentación

Guía de Análisis - Guía completa de las funciones de análisis
Prompts y Recursos - Documentación detallada de prompts y recursos de MCP
Documentación de API - Documentación oficial de la API de Kaltura

Desarrollo

Ejecución de Pruebas

pytest

Formato de Código

black src/
ruff check src/

Licencia

MIT