youtube-analytics-mcp

Un servidor MCP local, de solo lectura, que le da a Claude acceso a los datos privados de Analytics de tu canal de YouTube — visualizaciones, tiempo de visualización, retención, suscriptores, fuentes de tráfico, datos demográficos de la audiencia, ingresos e impresiones de miniaturas/CTR. No solo lo que cualquier clave de API pública ya puede ver.

Nada en este servidor puede editar, subir, publicar ni eliminar nada en tu canal. Consulta SECURITY.md para la revisión de seguridad completa.

Requisitos

• Node.js 22+

• Una cuenta de Google que sea propietaria (o gestione) del canal de YouTube del que quieras obtener datos

• macOS, Linux o WSL (el flujo del navegador de npm run auth usa el comando open)

Related MCP server: youtube-mcp-server

Lista de configuración

Sigue estos pasos en orden. Los pasos 1–4 se hacen en Google Cloud Console; los pasos 5–8 se hacen en tu máquina.

1. Crea un proyecto de Google Cloud

Ve a console.cloud.google.com y crea un proyecto nuevo (o elige uno existente con el que te sientas cómodo).

2. Activa tres APIs

En tu proyecto, ve a APIs y servicios → Biblioteca y activa cada una de estas:

• YouTube Data API v3

• YouTube Analytics API

• YouTube Reporting API (solo se necesita para impresiones de miniaturas/CTR — consulta más abajo)

3. Configura la pantalla de consentimiento de OAuth

Ve a APIs y servicios → Pantalla de consentimiento de OAuth.

• Tipo de usuario: Externo (a menos que tengas una cuenta de Google Workspace, en cuyo caso Interno también funciona)

• Rellena los campos obligatorios de nombre de la aplicación / correo de soporte

• Añade los ámbitos (scopes) de Analytics cuando se te pida (u omítelo — la aplicación los solicita directamente; esta pantalla solo necesita existir)

• Publica la aplicación en Producción. Este es el paso que la gente se salta y luego choca contra un muro: las aplicaciones que quedan en modo "Pruebas" solo permiten iniciar sesión con cuentas que hayas añadido explícitamente como usuarios de prueba, y sus tokens de actualización caducan a los 7 días, lo que significa que tendrías que repetir el paso 6 cada semana. Publicar en Producción (sin enviarla a la revisión de verificación de Google) está bien para una herramienta personal — Google mostrará una advertencia de "aplicación no verificada" al iniciar sesión, y haces clic en Avanzado → Ir a [nombre de tu aplicación] (no seguro) para continuar. Eso es lo esperado y es seguro para tu propia aplicación.

4. Crea las credenciales de OAuth

Ve a APIs y servicios → Credenciales → Crear credenciales → ID de cliente de OAuth.

• Tipo de aplicación: Aplicación de escritorio

• Ponle cualquier nombre

• Copia el Client ID y el Client Secret que genera — los necesitarás en el paso 5

No es necesario registrar ninguna URI de redirección aquí; este servidor vincula un puerto local efímero en el momento de la autenticación y Google acepta cualquier dirección de loopback para clientes de tipo escritorio.

5. Instala y compila

git clone <this-repo-url>
cd youtube-analytics-mcp
npm install
npm run build

6. Configura tus credenciales

cp .env.example .env

Edita .env y pega el Client ID / Client Secret del paso 4:

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret

.env está en gitignore — nunca se incluirá en un commit. Configuración opcional:

• GOOGLE_API_KEY — no es necesaria para ninguna herramienta actual; déjala en blanco salvo que amplíes el servidor por tu cuenta.

• REVENUE_CURRENCY — su valor predeterminado es USD. Configúrala con la moneda de pago de AdSense (p. ej. BRL) si prefieres ver las cifras de ingresos en esa moneda; Google convierte en el lado del servidor.

7. Autentícate

npm run auth

Esto abre tu navegador para iniciar sesión en Google y guarda un token de actualización en ~/.youtube-analytics-mcp/token.json (permisos limitados solo a tu usuario — nunca en el repositorio). Solo necesitas hacerlo una vez — el servidor renueva el token de acceso automáticamente después.

Verifica que ha funcionado:

npm run auth:status

Deberías ver Authenticated y el nombre de tu canal.

8. Apunta Claude Code a él

Añádelo a tu configuración de MCP usando la ruta absoluta al dist/index.js de este proyecto:

{
  "mcpServers": {
    "youtube-analytics-channel": {
      "command": "node",
      "args": ["/absolute/path/to/youtube-analytics-mcp/dist/index.js"]
    }
  }
}

Reinicia Claude Code (o recarga los servidores de MCP) y deberías ver que las herramientas siguientes están disponibles.

Herramientas disponibles

Una nota sobre las impresiones y el CTR

YouTube no expone las impresiones de miniaturas ni el CTR a través de la API interactiva de Analytics (reports.query) en ninguna combinación de dimensión/filtro — esto se verificó directamente contra la API, no se asumió a partir de la documentación. Esos datos solo existen en el informe masivo "Reach report" de YouTube, una API de trabajos asíncronos aparte:

1. La primera llamada a get_impressions_and_ctr registra un trabajo de informes recurrente en Google.

2. Google tarda 24–48 horas en producir el primer informe y luego sigue generando informes nuevos aproximadamente a diario.

3. Cada llamada a get_impressions_and_ctr (o a get_top_videos ordenado por impresiones/CTR) sincroniza los informes recién disponibles en una caché local en ~/.youtube-analytics-mcp/reach-cache.json y luego responde desde esa caché.

Hasta que llegue el primer informe, estas herramientas devuelven impressions: 0, impressionsCtr: null y una note que explica el motivo. Esto es lo esperado en el primer uso, no un error.

Solución de problemas

• "Acceso bloqueado" durante npm run auth: tu pantalla de consentimiento de OAuth sigue en modo "Pruebas". Vuelve al paso 3 y añade tu cuenta como usuario de prueba o publica en Producción.

• NotAuthenticatedError al iniciar el servidor: ejecuta npm run auth.

• Los ingresos siempre son 0: o el canal no está monetizado, o las cifras son realmente cero para ese período. La herramienta nunca inventa ingresos — consulta el campo available de get_revenue_analytics para distinguir un fallo real de permisos/acceso de los ceros reales.

• get_impressions_and_ctr / get_top_videos ordenado por impresiones no devuelven nada: comprueba dataCoverage en la respuesta. Si earliestDate es null, el trabajo de informe masivo aún no ha producido su primer informe (puede tardar hasta 48h desde la primera llamada).

Pruebas

npm test

Ejecuta pruebas unitarias (el ejecutor de pruebas integrado de Node) que cubren la validación de fechas/períodos, el análisis de duraciones ISO-8601, el análisis de CSV, el mapeo de filas de informes de Analytics y el cálculo de comparación de períodos (incluido el caso límite de división por cero). Son solo pruebas de funciones puras — no simulan llamadas reales a la API de Google ni la renovación de tokens de OAuth; esas rutas se validaron manualmente contra un canal real durante el desarrollo.

Seguridad

Consulta SECURITY.md para el modelo de amenazas completo y la revisión del OWASP Top 10. En resumen: todo es de solo lectura, todos los secretos permanecen en tu máquina fuera del repositorio y cada valor proporcionado por el usuario que llega a una llamada a la API de Google se valida primero.

Licencia

MIT — consulta LICENSE.