MCP YouTube Extract

Extrae información de videos y canales de YouTube utilizando la API de Datos de YouTube.

GitHub
19
Prueba este MCPPatrocinado

Documentación

MCP YouTube Extract

PyPI version Python 3.13+ License: MIT Code style: black

Un servidor de Model Context Protocol (MCP) para operaciones de YouTube, que demuestra conceptos básicos de MCP, incluyendo herramientas y registro de eventos.

✨ ¡No se requiere clave API! Funciona directamente usando yt-info-extract para metadatos de video y yt-ts-extract para transcripciones.

Características

  • Servidor MCP: Un servidor MCP completamente funcional con:
    • Herramientas: Extrae información de videos de YouTube, incluyendo metadatos y transcripciones
    • Registro completo: Registro detallado en toda la aplicación
    • Manejo de errores: Manejo robusto de errores con lógica de respaldo para transcripciones
  • Integración con YouTube: Capacidades integradas de YouTube usando yt-info-extract y yt-ts-extract:
    • Extrae información del video (título, descripción, canal, fecha de publicación, número de vistas)
    • Obtén transcripciones de video con lógica de respaldo inteligente
    • Soporte para transcripciones creadas manualmente y generadas automáticamente
    • No se requiere clave API para la funcionalidad básica

📦 Disponible en PyPI

¡Este paquete ya está disponible en PyPI! Puedes instalarlo directamente con:

pip install mcp-youtube-extract

Visita la página del paquete: mcp-youtube-extract en PyPI

Instalación

Inicio rápido (Recomendado)

La forma más fácil de comenzar es instalar desde PyPI:

pip install mcp-youtube-extract

O usando pipx (recomendado para herramientas de línea de comandos):

pipx install mcp-youtube-extract

Esto instalará la última versión con todas las dependencias. Luego puedes ejecutar el servidor MCP directamente:

mcp_youtube_extract

Usando uv (Desarrollo)

Para desarrollo o si prefieres uv:

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and install the project
git clone https://github.com/sinjab/mcp_youtube_extract.git
cd mcp_youtube_extract

# Install dependencies (including dev dependencies)
uv sync --dev

# Set up your API key for development
cp .env.example .env
# Edit .env and add your YouTube API key

Desde el código fuente

  1. Clona el repositorio:

    git clone https://github.com/sinjab/mcp_youtube_extract.git
cd mcp_youtube_extract

  2. Instala en modo de desarrollo:

    uv sync --dev

Configuración

Variables de entorno

¡No se requiere configuración! El servidor funciona directamente usando yt-info-extract para la extracción de metadatos.

Opcional: Para funcionalidad mejorada, puedes configurar opcionalmente una clave API de YouTube:

# Optional YouTube API Configuration
YOUTUBE_API_KEY=your_youtube_api_key_here

Opcional:

  • YOUTUBE_API_KEY: Tu clave API de YouTube Data (opcional, proporciona respaldo adicional para la extracción de metadatos)

Cómo obtener tu clave API de YouTube (Opcional)

Aunque no es necesario, puedes configurar opcionalmente una clave API de YouTube Data para funcionalidad mejorada. Así es como obtenerla:

Paso 1: Crea un proyecto en Google Cloud

  1. Ve a la Consola de Google Cloud
  2. Haz clic en "Seleccionar un proyecto" en la parte superior de la página
  3. Haz clic en "Nuevo proyecto" y asígnale un nombre (por ejemplo, "MCP YouTube Extract")
  4. Haz clic en "Crear"

Paso 2: Habilita la API de YouTube Data

  1. En tu nuevo proyecto, ve a la Biblioteca de API
  2. Busca "YouTube Data API v3"
  3. Haz clic en ella y luego en "Habilitar"

Paso 3: Crea credenciales de API

  1. Ve a la página de Credenciales
  2. Haz clic en "Crear credenciales" y selecciona "Clave de API"
  3. Tu nueva clave de API se mostrará - cópiala inmediatamente
  4. Haz clic en "Restringir clave" para asegurarla (recomendado)

Paso 4: Restringe tu clave de API (Recomendado)

  1. En la configuración de la clave de API, haz clic en "Restringir clave"
  2. En "Restricciones de API", selecciona "Restringir clave"
  3. Elige "YouTube Data API v3" del menú desplegable
  4. Haz clic en "Guardar"

Paso 5: Configura la facturación (Requerido)

  1. Ve a la página de Facturación
  2. Vincula una cuenta de facturación a tu proyecto
  3. Nota: La API de YouTube Data tiene un nivel gratuito de 10,000 unidades por día, que generalmente es suficiente para la mayoría de los casos de uso

Límites de uso de la clave API

  • Nivel gratuito: 10,000 unidades por día
  • Costo: $5 por cada 1,000 unidades después del nivel gratuito
  • Nota: La clave API solo se usa como respaldo cuando yt-info-extract falla
  • La mayoría de los usuarios no necesitarán una clave API ya que yt-info-extract maneja la mayoría de las solicitudes

Mejores prácticas de seguridad

  • Nunca subas tu clave API al control de versiones
  • Usa variables de entorno como se muestra en la sección de configuración
  • Restringe tu clave API solo a la API de YouTube Data
  • Monitorea el uso en la Consola de Google Cloud

Uso

Ejecutando el servidor MCP

Usando la instalación desde PyPI (Recomendado)

# Install from PyPI
pip install mcp-youtube-extract

# Run the server
mcp_youtube_extract

Usando la configuración de desarrollo

# Using uv
uv run mcp_youtube_extract

# Or directly
python -m mcp_youtube_extract.server

Ejecutando pruebas

# Run all pytest tests
uv run pytest

# Run specific pytest test
uv run pytest tests/test_with_api_key.py

# Run tests with coverage
uv run pytest --cov=src/mcp_youtube_extract --cov-report=term-missing

Nota: El directorio tests/ contiene 4 archivos:

  • test_context_fix.py - Prueba de pytest para la funcionalidad de respaldo de API de contexto
  • test_with_api_key.py - Prueba de pytest para funcionalidad completa con clave API
  • test_youtube_unit.py - Pruebas unitarias para la funcionalidad principal de YouTube
  • test_inspector.py - Script de inspección independiente (no es una prueba de pytest)

Cobertura de pruebas: El proyecto actualmente tiene una cobertura general del 62% con excelente cobertura de la funcionalidad principal:

  • youtube.py: 81% de cobertura (lógica de negocio principal)
  • logger.py: 73% de cobertura (utilidades de registro)
  • server.py: 22% de cobertura (manejo de protocolo MCP)
  • __init__.py: 100% de cobertura (inicialización del paquete)

Ejecutando el script de inspección

El archivo test_inspector.py es un script independiente que se conecta al servidor MCP y valida su funcionalidad:

# Run the inspection script to test server connectivity and functionality
uv run python tests/test_inspector.py

Este script:

  • Se conectará al servidor MCP
  • Listará las herramientas, recursos y avisos disponibles
  • Probará la herramienta get_yt_video_info con un video de muestra
  • Validará que el servidor esté funcionando correctamente

Usando la herramienta de YouTube

El servidor proporciona una herramienta principal: get_yt_video_info

Esta herramienta toma un ID de video de YouTube y devuelve:

  • Metadatos del video (título, descripción, canal, fecha de publicación, número de vistas) mediante yt-info-extract
  • Transcripción del video (con lógica de respaldo para diferentes tipos de transcripción) mediante yt-ts-extract

Ejemplo de uso:

# Extract video ID from YouTube URL: https://www.youtube.com/watch?v=dQw4w9WgXcQ
video_id = "dQw4w9WgXcQ"
result = get_yt_video_info(video_id)

Configuración del cliente

Para usar este servidor MCP con un cliente, agrega la siguiente configuración a la configuración de tu cliente:

Usando la instalación desde PyPI (Recomendado)

{
  "mcpServers": {
    "mcp_youtube_extract": {
      "command": "mcp_youtube_extract"
    }
  }
}

Con clave API opcional:

{
  "mcpServers": {
    "mcp_youtube_extract": {
      "command": "mcp_youtube_extract",
      "env": {
        "YOUTUBE_API_KEY": "your_youtube_api_key"
      }
    }
  }
}

Usando la configuración de desarrollo

{
  "mcpServers": {
    "mcp_youtube_extract": {
      "command": "uv",
      "args": [
        "--directory",
        "<your-project-directory>",
        "run",
        "mcp_youtube_extract"
      ]
    }
  }
}

Con clave API opcional:

{
  "mcpServers": {
    "mcp_youtube_extract": {
      "command": "uv",
      "args": [
        "--directory",
        "<your-project-directory>",
        "run",
        "mcp_youtube_extract"
      ],
      "env": {
        "YOUTUBE_API_KEY": "your_youtube_api_key"
      }
    }
  }
}

Desarrollo

Estructura del proyecto

mcp_youtube_extract/
├── src/
│   └── mcp_youtube_extract/
│       ├── __init__.py
│       ├── server.py          # MCP server implementation
│       ├── google_api.py      # yt-info-extract integration
│       ├── transcript_api.py  # yt-ts-extract integration
│       ├── youtube.py         # Unified API facade
│       └── logger.py          # Logging configuration
├── tests/
│   ├── __init__.py
│   ├── test_context_fix.py    # Context API fallback tests
│   ├── test_inspector.py      # Server inspection tests
│   ├── test_with_api_key.py   # Full functionality tests
│   └── test_youtube_unit.py   # Unit tests for core functionality
├── logs/                      # Application logs
├── .env                       # Environment variables (create from .env.example)
├── .gitignore                 # Git ignore rules (includes coverage files)
├── pyproject.toml
├── LICENSE                    # MIT License
└── README.md

Estrategia de pruebas

El proyecto utiliza un enfoque integral de pruebas:

  1. Pruebas unitarias (test_youtube_unit.py): Prueban la funcionalidad principal de YouTube con yt-info-extract simulado
  2. Pruebas de integración (test_context_fix.py, test_with_api_key.py): Prueban la funcionalidad completa del servidor
  3. Validación manual (test_inspector.py): Herramienta interactiva de inspección del servidor

Manejo de errores

El proyecto incluye manejo robusto de errores:

  • Fallos de extracción elegantes: Devuelve mensajes de error apropiados en lugar de fallar
  • Múltiples estrategias de respaldo: yt-info-extract proporciona respaldo automático entre YouTube Data API, yt-dlp y pytubefix
  • Lógica de respaldo de transcripciones: Múltiples estrategias para la recuperación de transcripciones mediante yt-ts-extract
  • Respuestas de error consistentes: Formato de mensaje de error estandarizado
  • Registro completo: Registros detallados para depuración y monitoreo

Compilación

# Install build dependencies
uv add --dev hatch

# Build the package
uv run hatch build

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENCIA para más detalles.

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar una Solicitud de Extracción (Pull Request).

Cómo comenzar

  1. Haz un fork del repositorio
  2. Crea una rama de características (git checkout -b feature/amazing-feature)
  3. Confirma tus cambios (git commit -m 'Add some amazing feature')
  4. Sube la rama (git push origin feature/amazing-feature)
  5. Abre una Solicitud de Extracción

Soporte

Si encuentras algún problema o tienes preguntas, por favor:

  1. Consulta los problemas existentes
  2. Crea un nuevo problema con información detallada sobre tu problema
  3. Incluye registros y mensajes de error cuando sea aplicable