youtube-analytics-mcp

Un servidor MCP que le da a un asistente de IA toda la superficie de YouTube Analytics, Data v3 y Reporting API para los canales que posees, incluidos varios canales a la vez.

La mayoría de los servidores MCP de YouTube codifican un puñado de cadenas de métricas, por lo que la primera pregunta fuera de su lista preestablecida no se puede responder sin bifurcarlos. Este está construido al revés: youtube_analytics_query acepta todos los parámetros que reports.query acepta, y youtube_data_call / youtube_reporting_call hacen lo mismo para las otras dos APIs. Los ajustes preestablecidos son conveniencias adicionales, nunca la única vía para algo.

Tú aportas tu propio cliente OAuth de Google Cloud. No se envía nada con este paquete, ninguna credencial pasa por un tercero, y todo se ejecuta localmente a través de stdio.

Herramientas

Cada herramienta de datos acepta una account opcional, por lo que una conversación puede comparar dos canales.

Los resultados grandes van a un archivo, no a través del modelo

youtube_analytics_query, youtube_data_call y youtube_reporting_call aceptan outputPath (y format opcional: csv o json, de lo contrario se infiere de la extensión). Con él, el resultado completo se escribe en disco y solo un resumen — recuento de filas, columnas, tamaño en bytes, primeras tres filas — regresa. Sin él, los resultados de más de 100 filas se truncan con un puntero a la opción, porque un informe de mil filas devuelto en línea le cuesta al llamante su ventana de contexto y es ilegible cuando llega.

Para trabajo realmente masivo — cada día de cada video, durante meses — usa la Reporting API a través de youtube_reporting_call: produce informes CSV diarios descargables con combinaciones de dimensiones que reports.query no devolverá en una sola llamada.

Related MCP server: YouTube MCP Server

Configuración

1. Un cliente OAuth de Google Cloud, una vez

• Crea o elige un proyecto.

• APIs y servicios → Biblioteca: habilita YouTube Analytics API, YouTube Data API v3 y YouTube Reporting API.

• Pantalla de consentimiento de OAuth → Audiencia: establece el tipo de usuario en Externo (Interno solo se ofrece cuando hay una organización de Workspace adjunta). En esa misma página de Audiencia, en Usuarios de prueba, haz clic en + Agregar usuarios y agrega la cuenta de Google de cada propietario de canal — incluida la tuya.

  Si te lo pierdes, el consentimiento falla con "… no ha completado el proceso de verificación de Google. La aplicación se está probando actualmente y solo pueden acceder a ella los evaluadores aprobados por el desarrollador." Ser el propietario del proyecto no te convierte en usuario de prueba; tienes que agregarte explícitamente.

• Establece el estado de publicación en En producción. Esto importa más de lo que parece. Google:

  Un proyecto de Google Cloud Platform con una pantalla de consentimiento de OAuth configurada para un tipo de usuario externo y un estado de publicación de "Prueba" recibe un token de actualización que caduca en 7 días, a menos que los únicos alcances de OAuth solicitados sean un subconjunto de nombre, dirección de correo electrónico y perfil de usuario.

  Cada alcance de YouTube es sensible, por lo que una aplicación en Prueba te obliga a reautorizar cada semana.

  Ten en cuenta que publicar no es simplemente un interruptor para estos alcances: es probable que la consola requiera un video de demostración y someta la aplicación a la revisión de verificación de la API de YouTube antes de que te permita salir de Prueba. Eso es trabajo real para una herramienta personal, y el re-consentimiento semanal a menudo es el mejor intercambio. Consulta El límite de concesión de 7 días a continuación para conocer las alternativas.

• Credenciales → Crear credenciales → ID de cliente de OAuth → Aplicación de escritorio. No Aplicación web: este servidor escucha en un puerto de bucle invertido libre y aleatorio en cada ejecución, y un cliente web requiere que cada URI de redirección, incluido el puerto, se registre de antemano.

• Descarga el JSON.

2. Dile al servidor dónde está el cliente

Ponlo en el archivo de configuración (consulta config.example.json):

// %APPDATA%\youtube-analytics-mcp\config.json          (Windows)
// ~/Library/Application Support/youtube-analytics-mcp/  (macOS)
// ~/.config/youtube-analytics-mcp/config.json           (Linux)
{
  "client": { "client_id": "...", "client_secret": "..." }
}

Ejecuta youtube-analytics-mcp --where para imprimir ese directorio. Las variables de entorno también funcionan y tienen prioridad — YTMCP_CLIENT_ID + YTMCP_CLIENT_SECRET, o YTMCP_CLIENT_FILE apuntando a la descarga de Google tal cual (el envoltorio {"installed": …} se desenvuelve por ti). YTMCP_CONFIG_DIR reubica todo el directorio.

3. Autoriza cada canal

bun run auth                      # or: youtube-analytics-mcp --authorize
bun run auth -- --alias second    # name it yourself

Tu navegador se abre automáticamente en la página de consentimiento; la URL también se imprime, para los casos en que no puede (SSH, contenedores, CI). Elige la cuenta de Google que posee el canal y aprueba. Repite para cada canal — elige una cuenta diferente en el navegador cada vez. Las cuentas se nombran según su @handle a menos que pases --alias.

Establece YTMCP_NO_BROWSER=1 para no abrir nunca un navegador, o pasa openBrowser: false a la herramienta youtube_authorize para una sola llamada.

Los tokens de actualización se escriben en accounts.json en el mismo directorio, separados del config.json que editas a mano, por lo que el archivo que podrías pegar en un informe de errores nunca es el archivo que contiene los tokens. Ambos se escriben con 0600 donde la plataforma lo respeta.

Tu asistente también puede manejar esto. youtube_authorize devuelve la URL de consentimiento de inmediato y sigue escuchando en segundo plano; youtube_authorize_status informa cómo terminó. No se bloquea, porque el consentimiento tarda tanto como tarda un humano y los clientes MCP abandonan una llamada de herramienta mucho antes. La URL también se escribe en pending-auth.txt en el directorio de configuración, ya que la mayoría de los clientes descartan el stderr de un servidor y una URL que nadie puede leer no sirve.

4. Regístrate con tu cliente MCP

Claude Code:

claude mcp add youtube-analytics --scope user -- bunx youtube-analytics-mcp

O a mano, en el mapa mcpServers de cualquier cliente:

{
  "mcpServers": {
    "youtube-analytics": { "command": "bunx", "args": ["youtube-analytics-mcp"] }
  }
}

Solo lectura por defecto

Actualizar un video, publicar o moderar comentarios y subir miniaturas no son reversibles en un canal en vivo, por lo que el alcance de escritura no se solicita y las llamadas que no sean GET se rechazan. Para habilitarlas, establece YTMCP_ALLOW_WRITE=1 y vuelve a autorizar — la bandera sola no hace nada, porque el token almacenado no lleva el alcance.

Espectadores concurrentes y la forma de consulta que nadie adivina

averageConcurrentViewers y peakConcurrentViewers sí funcionan en transmisiones finalizadas, y coinciden exactamente con los números de Studio. Se cree ampliamente que no existen porque la API los rechaza en todas las formas excepto una: el filtro debe fijar un solo video y dimensions debe ser livestreamPosition.

Ningún error nombra la dimensión faltante, y el 500 en particular se lee como si la métrica estuviera rota en lugar de que la solicitud estuviera mal. youtube_concurrent_curve lo arma por ti y devuelve el pico, la media y toda la curva minuto a minuto.

Lo que genuinamente no puede darte

youtube_capabilities devuelve la lista actual. Ambos se verificaron pidiendo la métrica y obteniendo Unknown identifier de vuelta, que es como la API distingue un nombre que nunca ha oído de uno que conoce pero no puede servir aquí:

• Totales de mensajes de chat en vivo y reacciones. Solo en Studio. liveChatMessages lee un chat en tiempo real y no puede recuperar uno finalizado.

• Impresiones y tasa de clics de impresiones. Solo en Studio, en la pestaña Alcance.

Dos cosas que vale la pena saber

No existe una ventana "desde la publicación". La API de Analytics es puramente por rango de fechas, por lo que una ventana que cubre el día de una transmisión devuelve la audiencia en vivo de esa transmisión por construcción. La ventana predeterminada por video de Studio excluye todo el período en vivo, lo cual es una trampa fácil y costosa al analizar transmisiones en vivo. Esta API no puede caer en ella.

La cuota de Analytics es separada. Las APIs de Analytics y Reporting miden de forma independiente del presupuesto diario de unidades de la Data API v3, por lo que consultar aquí no consume la cuota por la que compite el sondeo de chat en vivo. Inferencia sólida de que son APIs distintas con sus propias páginas de cuota en la consola — no medido.

Desarrollo

bun install
bun run dev          # start on stdio
bunx tsc --noEmit    # typecheck
bun run inspector    # MCP Inspector

MIT.

La API se retrasa unos días

Los datos finalizados de Analytics no están disponibles de inmediato. Medido el 2026-08-25, las filas de la dimensión de día llegaron hasta el 08-22 y se detuvieron: las sesiones de los tres días anteriores no devolvieron filas en absoluto, no filas cero. Una consulta para una transmisión que terminó hace horas parecerá un canal sin tráfico.

La interfaz web de Studio tiene una ruta en tiempo real que la API no expone, por lo que los informes del mismo día todavía tienen que venir de Studio. Usa este servidor para todo lo que tenga más de aproximadamente tres días, donde es mucho mejor que hacer clic en Studio video por video.

El límite de concesión de 7 días y por qué ningún código puede sortearlo

Mientras el estado de publicación del proyecto de Cloud sea Prueba con un tipo de usuario Externo, Google revoca los tokens de actualización después de 7 días a menos que los únicos alcances solicitados sean nombre, correo electrónico y perfil. Cada alcance de YouTube es sensible, por lo que la excepción nunca se aplica aquí.

Esto no se puede automatizar. Los 7 días están en el token de actualización. Acuñar uno nuevo requiere que un humano apruebe una pantalla de consentimiento en un navegador — eso es lo que significa consentimiento, no un vacío que se pueda ingeniar. Actualizar los tokens de acceso con más frecuencia no lo toca.

Lo que este servidor hace en su lugar:

• youtube_accounts informa el ageDays de cada concesión y advierte desde el día 5.

• Una concesión caducada falla con un mensaje que nombra la causa y la solución, no un invalid_grant desnudo.

• youtube_refresh_tokens (o --refresh desde la CLI) ejercita cada concesión como una verificación de salud. También es una cobertura: no está establecido si el reloj de 7 días es absoluto desde la emisión o se desliza con el uso. Si se desliza, ejecutarlo diariamente en un programador mantiene las concesiones vivas indefinidamente; si no, la llamada cuesta casi nada. Vale la pena ejecutarlo de cualquier manera.

• Re-consentir es una llamada a youtube_authorize, que abre el navegador por sí mismo — alrededor de quince segundos.

Las soluciones reales, en orden de costo:

1. Estado de publicación → En producción. Gratis, y las autorizaciones dejan de caducar. Para los ámbitos sensibles de YouTube, Google puede exigir un vídeo de demostración y una revisión de verificación antes de permitirte publicar, lo que supone bastante trabajo para una herramienta personal.

2. Tipo de usuario interno. Sin límite de 7 días y sin verificación, pero la opción solo existe cuando el proyecto pertenece a una organización de Google Workspace — una suscripción de pago.

3. Activa con reautorización semanal. Para una herramienta de un solo usuario, esta suele ser la respuesta correcta.