Kaltura MCP Server

Um servidor para realizar operações seguras e somente leitura na API do Kaltura.

GitHub
5
Experimente este MCPPatrocinado

Documentação

Kaltura MCP Server

Um servidor Model Context Protocol (MCP) que fornece ferramentas seguras e somente leitura para gerenciar operações da API Kaltura. Este servidor permite que assistentes de IA pesquisem, descubram e analisem conteúdo de mídia Kaltura com segurança.

Recursos

  • Descoberta de Mídia: Pesquise e navegue por entradas de mídia com filtros avançados
  • Análise de Conteúdo: Acesse legendas, transcrições e conteúdo de anexos
  • Gerenciamento de Categorias: Navegue e explore categorias de conteúdo
  • Analytics: Recupere métricas de visualização e desempenho
  • Acesso Seguro: Operações somente leitura com validação abrangente de entrada
  • Gerenciamento de Sessão: Tratamento automático de sessão com expiração configurável

Instalação

  1. Clone este repositório:
git clone https://github.com/zoharbabin/kaltura-mcp.git
cd kaltura-mcp
  1. Instale as dependências:
pip install -e .

Modos de Uso

Este servidor suporta dois modos de implantação:

🔧 Servidor MCP Local (Modo Stdio)

Melhor para: Uso pessoal, integração direta com Claude Desktop, desenvolvimento

🌐 Servidor MCP Remoto (Modo HTTP/SSE)

Melhor para: Serviços hospedados, múltiplos usuários, implantações de produção

Configuração do Servidor MCP Local (Claude Desktop)

Passo 1: Instalar o Pacote

pip install kaltura-mcp

Passo 2: Configurar o Ambiente

🔒 Método Seguro (Recomendado): Use o script de configuração interativo:

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

# Run the interactive setup
python setup_env.py

O script irá guiá-lo através de:

  1. Escolha entre modo stdio (local) ou remoto
  2. Inserção segura das suas credenciais Kaltura
  3. Geração de um arquivo .env com permissões adequadas (600)
  4. Fornecimento da configuração exata do Claude Desktop

📋 Método Manual: Copie e edite o arquivo de exemplo:

# 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

Passo 3: Obtenha Suas Credenciais Kaltura

Você precisará destas credenciais da sua conta Kaltura:

  • URL do Serviço: URL do seu servidor Kaltura (geralmente https://cdnapisec.kaltura.com)
  • ID do Parceiro: Seu ID de parceiro numérico (encontrado em KMC → Configurações → Configurações de Integração)
  • Segredo do Administrador: Sua chave secreta de administrador da API (encontrada em KMC → Configurações → Configurações de Integração)
  • ID do Usuário: Seu ID de usuário Kaltura (geralmente seu e-mail ou admin)

Passo 4: Configurar o Claude Desktop

Abra o arquivo de configuração do Claude Desktop:

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

🔒 Configuração Segura (credenciais no arquivo .env):

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

Notas Importantes:

  • Substitua /full/path/to/kaltura-mcp pelo caminho real para o seu comando kaltura-mcp (encontre-o com which kaltura-mcp)
  • O arquivo .env é carregado automaticamente do diretório do projeto pelo servidor
  • O script setup_env.py detectará e fornecerá automaticamente o caminho correto do comando

Passo 5: Reinicie o Claude Desktop

Após salvar o arquivo de configuração, reinicie o Claude Desktop completamente para que as alterações tenham efeito.

Passo 6: Teste a Integração

No Claude Desktop, tente perguntar:

  • "Pesquise vídeos recentes do Kaltura"
  • "Liste minhas categorias Kaltura"
  • "Encontre vídeos sobre [tópico] na minha conta Kaltura"

Solução de Problemas na Configuração Local

Problema: Comando kaltura-mcp não encontrado

  • Solução: Certifique-se de que você instalou com pip install kaltura-mcp e que o comando está no seu PATH

Problema: "Erro: Variáveis de ambiente obrigatórias ausentes"

  • Solução:
    1. Verifique se o arquivo .env existe no diretório do seu projeto
    2. Verifique as permissões do arquivo: ls -la .env (deve mostrar -rw-------)
    3. Certifique-se de que todas as credenciais Kaltura necessárias estão definidas no arquivo .env

Problema: "Credenciais inválidas" ou "Falha na autenticação"

  • Solução:
    1. Verifique suas credenciais em KMC → Configurações → Configurações de Integração
    2. Verifique se há erros de digitação ou espaços extras no arquivo .env
    3. Execute python setup_env.py para recriar a configuração

Problema: O Claude Desktop não mostra o servidor MCP

  • Solução:
    1. Verifique a sintaxe do arquivo de configuração com um validador JSON
    2. Verifique se o caminho do comando está correto (use which kaltura-mcp)
    3. Reinicie o Claude Desktop completamente
    4. Verifique os logs do Claude Desktop para mensagens de erro

Problema: Erro ".env file not found"

  • Solução:
    1. Execute python setup_env.py a partir do diretório do seu projeto
    2. Certifique-se de que o arquivo .env existe no mesmo diretório do código do servidor
    3. Verifique as permissões do arquivo: ls -la .env (deve mostrar -rw-------)

✅ Benefícios de Segurança:

  • ✅ Permissões de arquivo seguras (600 - somente proprietário)
  • ✅ Ignorado pelo Git por padrão (não será commitado)
  • ✅ Local ao diretório do projeto (fácil de gerenciar)
  • ✅ Padrão .env (familiar para desenvolvedores)
  • ✅ Sem credenciais em arquivos de configuração (segurança aprimorada)

Configuração do Servidor MCP Remoto

Configuração

Para implantação remota/hospedada, variáveis de ambiente adicionais são necessárias:

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

Variáveis de ambiente obrigatórias:

  • JWT_SECRET_KEY: Chave secreta forte para assinatura de tokens JWT (⚠️ CRÍTICO PARA SEGURANÇA)
  • OAUTH_REDIRECT_URI: URL de callback OAuth (ex.: https://your-domain.com/oauth/callback)
  • SERVER_HOST: Endereço de bind do servidor (padrão: 0.0.0.0)
  • SERVER_PORT: Porta do servidor (padrão: 8000)

Variáveis de ambiente opcionais:

  • SERVER_RELOAD: Habilitar auto-reload em desenvolvimento (padrão: false)
  • OAUTH_CLIENT_ID: ID de cliente OAuth personalizado
  • OAUTH_CLIENT_SECRET: Segredo de cliente OAuth personalizado

Executando o Servidor Remoto

# Using the installed command
kaltura-mcp-remote

# Or using Python module
python -m kaltura_mcp.remote_server

O servidor remoto fornece:

  • Transporte HTTP/SSE para o protocolo MCP
  • Autenticação baseada em JWT para gerenciamento seguro de credenciais
  • Fluxo de autorização baseado na web para configuração amigável
  • Suporte multi-tenant para hospedagem como serviço

Ferramentas Disponíveis

  1. get_media_entry - Obtenha informações detalhadas sobre uma entrada de mídia específica

    • Parâmetros: entry_id (obrigatório)

  2. list_categories - Liste e pesquise categorias de conteúdo

    • Parâmetros: search_text, limit

  3. Ferramentas de Analytics - Suíte abrangente de analytics com funções específicas:

    • get_analytics - Dados gerais de analytics para relatórios e análise
    • get_analytics_timeseries - Dados de série temporal otimizados para gráficos
    • get_video_retention - Análise detalhada de retenção de espectadores ao longo dos vídeos
    • get_realtime_metrics - Analytics ao vivo atualizados a cada ~30 segundos
    • get_quality_metrics - Qualidade de Experiência (QoE) e desempenho de streaming
    • get_geographic_breakdown - Analytics baseados em localização em várias granularidades
    • list_analytics_capabilities - Descubra todas as funções de analytics disponíveis
    • Veja Guia de Analytics para uso detalhado

  4. get_download_url - Obtenha URL de download direto para arquivos de mídia

    • Parâmetros: entry_id (obrigatório), flavor_id

  5. get_thumbnail_url - Obtenha URL de miniatura/imagem de pré-visualização do vídeo com dimensões personalizadas

    • Parâmetros: entry_id (obrigatório), width, height, second

  6. search_entries - Pesquise e descubra entradas de mídia com ordenação e filtragem inteligentes

    • Parâmetros: query (obrigatório), search_type, match_type, specific_field, boolean_operator, include_highlights, custom_metadata, date_range, max_results, sort_field, sort_order

  7. list_caption_assets - Liste legendas e subtítulos disponíveis para uma entrada de mídia

    • Parâmetros: entry_id (obrigatório)

  8. get_caption_content - Obtenha conteúdo de legenda/subtítulo e URL de download

    • Parâmetros: caption_asset_id (obrigatório)

  9. list_attachment_assets - Liste ativos de anexo para uma entrada de mídia

    • Parâmetros: entry_id (obrigatório)

  10. get_attachment_content - Obtenha detalhes do conteúdo do anexo e baixe o conteúdo como base64

    • Parâmetros: attachment_asset_id (obrigatório)

Prompts

O servidor fornece prompts inteligentes para guiar os usuários em fluxos de trabalho complexos:

  1. analytics_wizard - Guia interativo para criar relatórios abrangentes de analytics

    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 - Assistente de busca em linguagem natural para encontrar mídia

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

  3. accessibility_audit - Verificador de conformidade de acessibilidade de conteúdo

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

  4. retention_analysis - Crie relatório abrangente de análise de retenção

    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

O servidor expõe dados usados com frequência como recursos em cache:

  1. kaltura://analytics/capabilities - Documentação completa de analytics

    • Todos os 60+ tipos de relatório com descrições
    • Métricas e dimensões disponíveis
    • Melhores práticas para diferentes casos de uso
    • Cache por 30 minutos

  2. kaltura://categories/tree - Hierarquia de categorias com contagens de entradas

    • Estrutura completa da árvore de categorias
    • Contagens de entradas por categoria
    • Relações pai-filho
    • Cache por 30 minutos

  3. kaltura://media/recent/{count} - Entradas de mídia recentes

    • Substitua {count} pelo número de entradas (ex.: kaltura://media/recent/20)
    • Máximo de 100 entradas
    • Inclui metadados básicos
    • Cache por 5 minutos

Servidor MCP Remoto (Avançado)

Fluxo de Autorização do Usuário

  1. Implantação do Servidor: Implante o servidor remoto no seu ambiente de hospedagem
  2. Autorização do Usuário: Os usuários visitam https://your-server.com/oauth/authorize
  3. Inserção de Credenciais: Os usuários inserem suas credenciais Kaltura com segurança via formulário web
  4. Geração de Token: O servidor gera um token JWT com credenciais criptografadas
  5. Configuração do Cliente: Os usuários adicionam a URL do servidor e o token ao seu cliente MCP

Configuração Remota Passo a Passo

1. Gere um Segredo JWT Seguro

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

2. Configure o Ambiente

# 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. Implante o Servidor

Opção A: Python Direto

kaltura-mcp-remote

Opção B: Docker

docker-compose up -d

Opção C: Produção com 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. Onboarding do Usuário

Envie os usuários para: https://your-server.com/oauth/authorize?response_type=code&client_id=kaltura-mcp&redirect_uri=https://your-server.com/oauth/callback&state=user123

5. Configuração do Cliente

Para Claude Desktop (Modo Remoto):

A maneira mais fácil de usar o servidor remoto com Claude Desktop é através do 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"
      }
    }
  }
}

O cliente proxy (kaltura-mcp-proxy) atua como um servidor MCP stdio local que encaminha solicitações para o seu servidor remoto. Isso fornece a melhor compatibilidade com 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"
  }
});

Documentação de Analytics

O servidor MCP fornece uma suíte abrangente de analytics com funções específicas otimizadas para diferentes casos de uso:

Funções de Analytics Específicas:

  • get_analytics: Dados abrangentes de relatórios em formato de tabela para análise detalhada
  • get_analytics_timeseries: Dados de série temporal otimizados para gráficos e visualizações
  • get_video_retention: Curvas detalhadas de retenção de espectadores mostrando exatamente onde os espectadores desistem
  • get_realtime_metrics: Analytics ao vivo atualizados a cada ~30 segundos para monitoramento
  • get_quality_metrics: Métricas de Qualidade de Experiência (QoE) para desempenho de streaming
  • get_geographic_breakdown: Analytics baseados em localização em nível de país, região ou cidade

Capacidades de Analytics:

  • 60+ tipos de relatório cobrindo conteúdo, usuários, geografia, plataformas e mais
  • Acesso a dados brutos para análise e visualização personalizadas
  • Insights inteligentes incluindo pontos de desistência e padrões de engajamento
  • Suporte para filtragem por intervalos de datas, categorias, usuários e dimensões

Para documentação abrangente, veja:

Considerações de Segurança

Implantação em Produção

  • Use HTTPS: Sempre implante com certificados TLS/SSL
  • Segredo JWT Seguro: Use uma chave secreta criptograficamente forte (32+ bytes)
  • Segurança do Ambiente: Nunca commite segredos no controle de versão
  • Segurança de Rede: Use firewalls e acesso VPN quando apropriado
  • Atualizações Regulares: Mantenha as dependências atualizadas para correções de segurança

Segurança do Token JWT

  • Expiração do Token: Os tokens expiram após 24 horas por padrão
  • Criptografia de Credenciais: As credenciais Kaltura são criptografadas dentro do payload JWT
  • Limitação de Escopo: Os tokens são limitados a operações Kaltura somente leitura
  • Revogação: Reinicie o servidor para invalidar todos os tokens existentes

Infraestrutura

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

Implantação Docker

docker-compose.yml para produção:

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"

Monitoramento e Registros

O servidor remoto fornece registro integrado e pode ser monitorado via:

  • Verificação de Saúde: GET / retorna o status do servidor
  • Métricas: Acesse os logs via volumes Docker ou logs do servidor
  • Rastreamento de Erros: Configure serviços externos de rastreamento de erros

Notas Importantes de Segurança

Segurança no Modo Local (Recomendado)

  • ✅ Configuração Direta - Credenciais configuradas diretamente no Claude Desktop
  • ✅ Conformidade com Padrões MCP - O cliente passa credenciais ao servidor via variáveis de ambiente
  • ✅ Isolamento de Processo - O servidor MCP roda em processo isolado com escopo limitado
  • ✅ Sem exposição de rede - Comunicação direta com a API da Kaltura
  • ✅ Armazenamento local de credenciais - As credenciais nunca saem da sua máquina
  • ✅ Transmissão segura - Credenciais transmitidas com segurança ao processo do servidor MCP

Segurança no Modo Remoto

  • ✅ Criptografia de credenciais - Credenciais da Kaltura criptografadas em tokens JWT
  • ✅ Expiração de tokens - Expiração automática de tokens em 24 horas
  • ✅ Criptografia TLS - HTTPS obrigatório para produção
  • ⚠️ Confiança no servidor - Você deve confiar no operador do servidor remoto
  • ⚠️ Transmissão de credenciais - Credenciais enviadas ao servidor remoto (criptografadas)

Checklist de Produção

  • Use HTTPS com certificados válidos
  • Gere uma chave secreta JWT forte (32+ bytes)
  • Configure variáveis de ambiente seguras
  • Configure registro e monitoramento adequados
  • Implemente limitação de taxa (nginx/cloudflare)
  • Atualizações regulares de segurança
  • Plano de backup e recuperação de desastres

Arquiteturas de Implantação

Uso Pessoal (Recomendado)

Claude Desktop ←→ Local MCP Server ←→ Kaltura API

Pequena Equipe

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

Empresarial

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

Documentação

Desenvolvimento

Executando Testes

pytest

Formatação de Código

black src/
ruff check src/

Licença

MIT