Skip to main content
Glama
YouTube Metrics MCP Server

YouTube Metrics MCP Server

by ramedina-ia

📊 YouTube Metrics MCP Server

License: MIT Runtime Protocol IDE

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

Herramienta

Descripción

Parámetros

youtube_get_channel_info

Información general del canal autenticado (ID, título, suscriptores, vistas acumuladas).

Ninguno

youtube_get_channel_overview

Métricas consolidadas en un rango de fechas (vistas, watch time, duración media, suscripciones, ingresos).

startDate (YYYY-MM-DD), endDate (YYYY-MM-DD), includeMonetary (boolean)

youtube_get_video_analytics

Rendimiento puntual de un video específico (views, watch time, % medio visto, interacciones).

ideoId, startDate, endDate

youtube_get_retention_data

Curva de retención segundo a segundo (valores normalizados 0.0 - 1.0).

ideoId

youtube_get_traffic_sources

Desglose por fuente de tráfico (Búsqueda, Sugeridos, Shorts, Externo).

startDate, endDate, ideoId (opcional)

youtube_get_top_videos

Ranking de videos con mayor desempeño según la métrica indicada.

startDate, endDate, maxResults, orderBy ( iews o estimatedMinutesWatched)

youtube_get_demographics

Audiencia segmentada por rangos de edad y género.

startDate, endDate

youtube_get_geography

Audiencia distribuida por país de procedencia.

startDate, endDate, maxResults

youtube_update_video_metadata

Actualiza título, descripción (timestamps/capítulos de faster-whisper), tags y categoría.

videoId, title?, description?, tags?, categoryId?

youtube_set_video_thumbnail

Carga una miniatura personalizada para un video desde un archivo local (PNG/JPG, máx 2MB).

videoId, imagePath

youtube_post_comment

Publica un comentario comercial o informativo de nivel superior (WhatsApp, enlaces a repositorios).

videoId, text

youtube_reply_to_comment

Publica una respuesta oficial a un comentario de un espectador.

commentId, text

youtube_create_playlist

Crea una nueva lista de reproducción en el canal (pública, oculta o privada).

title, description?, privacyStatus?

youtube_add_video_to_playlist

Añade un video existente a una lista de reproducción específica.

playlistId, videoId


💬 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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables AI assistants to access YouTube organic analytics, including channel stats, video performance, watch time, and audience engagement, via the YouTube Data API v3 and Analytics API v2.
      6
      32 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients to query YouTube channel health, diagnose video performance, full-text search transcripts, and vet topics/scripts directly from an editor or chat interface.
      Apache 2.0