📊 YouTube Metrics MCP Server

Servidor MCP (Model Context Protocol) de alto rendimiento para la auditoría, análisis de retención segundo a segundo y monitoreo de analíticas de canales de YouTube en tiempo real, diseñado para operar directamente dentro del entorno de desarrollo agéntico Google Antigravity y clientes compatibles con MCP.

🚀 Características Principales

• Auditoría Integral de Canales: Consulta estadísticas generales (suscriptores, vistas acumuladas, videos publicados).

• Rendimiento Consolidado: Analiza periodos específicos con métricas de tiempo de visualización (Watch Time), duración media, interacciones (likes, comentarios, compartidos) y estado de monetización.

• Curva de Retención de Audiencia: Obtén la retención normalizada segundo a segundo de cualquier video para detectar el impacto de los ganchos (hooks), puntos de fuga y momentos de mayor retención.

• Desglose de Fuentes de Tráfico: Identifica de dónde proviene tu audiencia (Búsqueda de YouTube, videos sugeridos, feed de Shorts, fuentes externas).

• Ranking de Videos (Top Videos): Lista los contenidos con mejor desempeño en rangos de fechas personalizados.

• Datos Demográficos y Geográficos: Distribución de audiencia por edad, género y países.

• Autenticación Guiada: Script interactivo ( pm run auth) con servidor local temporal para canjear el token OAuth 2.0 de forma segura.

Related MCP server: yt-intel MCP Server

🛠️ Stack Tecnológico

• Entorno: Google Antigravity (Gemini 3.8 Flash / Gemini Pro)

• Protocolo: Model Context Protocol (MCP TypeScript SDK oficial @modelcontextprotocol/sdk)

• APIs de Google:

  • YouTube Data API v3

  • YouTube Analytics API v2

• Runtime: Node.js & TypeScript (modo nativo con --experimental-strip-types)

📋 Requisitos Previos

1. Node.js: Versión 20 o superior.

2. Proyecto en Google Cloud Platform (GCP):

   • Ingresa a Google Cloud Console.

   • Habilita las siguientes dos APIs en tu proyecto:

     • YouTube Data API v3

     • YouTube Analytics API

   • Configura la Pantalla de consentimiento de OAuth:

     • Tipo de usuario: Externo.

     • Agrega tu dirección de correo de Google como Usuario de prueba (Test user).

   • Crea las Credenciales:

     • Tipo: ID de cliente de OAuth 2.0.

     • Tipo de aplicación: Aplicación de escritorio (Desktop App).

     • Descarga o copia el Client ID y el Client Secret.

⚙️ Instalación y Configuración

1. Clonar el repositorio

ash git clone https://github.com/ramedina-ia/youtube-metrics-mcp.git cd youtube-metrics-mcp

2. Instalar dependencias

ash npm install

3. Configurar variables de entorno

Copia la plantilla .env.example a .env: ash cp .env.example .env Abre .env y coloca tus credenciales de Google Cloud: env YOUTUBE_CLIENT_ID=tu_client_id.apps.googleusercontent.com YOUTUBE_CLIENT_SECRET=tu_client_secret AUTH_PORT=3000

4. Vincular tu canal de YouTube (OAuth 2.0)

Ejecuta el asistente interactivo: ash npm run auth

• Se abrirá automáticamente una ventana en tu navegador solicitando autorización.

• Inicia sesión con la cuenta de Google propietaria o administradora del canal de YouTube.

• Una vez concedidos los permisos, el script capturará el callback y guardará automáticamente el YOUTUBE_REFRESH_TOKEN en tu .env.

🔌 Integración en Google Antigravity

Agrega el servidor en el archivo de configuración de MCP de Antigravity:

• Ubicación: ~/.gemini/antigravity/mcp_config.json (o ~/.gemini/config/mcp_config.json)

json { mcpServers: { youtube-metrics: { command: node, args: [ --experimental-strip-types, Ruta/Absoluta/A/youtube-metrics-mcp/src/index.ts ], env: { MCP_MODE: stdio } } } }

Nota para Windows: Asegúrate de escapar las barras invertidas en la ruta (ej: C:\Proyectos\youtube-metrics-mcp\src\index.ts).

🧰 Catálogo de Herramientas MCP

💬 Prompts de Ejemplo para Antigravity

Una vez configurado en Antigravity, puedes pedirle cosas como:

• Audita el rendimiento de mi canal de YouTube durante los últimos 30 días y dime qué videos atrajeron más suscriptores.

• Analiza la curva de retención del video con ID dQw4w9WgXcQ y detecta en qué segundo cae más del 20% de la audiencia.

• Actualiza la descripción del video VIDEO_ID agregando los timestamps y capítulos generados por Faster-Whisper.

• Sube la miniatura generada en C:/ruta/miniatura.png al video VIDEO_ID.

• Publica un comentario en el video VIDEO_ID con mi enlace de WhatsApp (+57 333 235 4749) para consultoría.

🔒 Seguridad y Buenas Prácticas

• Sin credenciales expuestas: El repositorio incluye .gitignore estricto que previene la subida accidental de archivos .env, tokens y archivos de credenciales.

• OAuth 2.0 Local: El flujo de autenticación corre exclusivamente en tu máquina local (localhost) y las credenciales nunca viajan a servidores de terceros.

• Acceso Granular: Utiliza los scopes oficiales de Google Cloud (youtube.force-ssl, youtube.readonly, yt-analytics.readonly), permitiendo tanto la consulta analítica como la gestión directa de metadatos dentro de la cuota gratuita diaria de 10,000 unidades.

📄 Licencia

Este proyecto está bajo la Licencia MIT. Consulta el archivo LICENSE para más detalles.