# 📊 YouTube Metrics MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Runtime](https://img.shields.io/badge/Node.js-%3E%3D20-green.svg)](https://nodejs.org/)
[![Protocol](https://img.shields.io/badge/Protocol-Model%20Context%20Protocol%20(MCP)-orange.svg)](https://modelcontextprotocol.io/)
[![IDE](https://img.shields.io/badge/Environment-Google%20Antigravity-4285F4.svg)](https://antigravity.google/)

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.

---

## 🛠️ Stack Tecnológico

- **Entorno**: [Google Antigravity](https://antigravity.google/) (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](https://console.cloud.google.com/).
   - 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](LICENSE) para más detalles.