YouTube Data MCP

Servidor MCP de YouTube de alta eficiencia que proporciona datos estructurados y optimizados en tokens para LLMs.

Documentación

Servidor MCP de YouTube Data (@kirbah/mcp-youtube)

Un servidor MCP de YouTube Data de calidad profesional, diseñado específicamente para agentes de IA.

A diferencia de los envoltorios de API estándar que inundan tu LLM con datos redundantes, este servidor elimina el pesado exceso de carga de YouTube. Está diseñado para ahorrarte una enorme cantidad de tokens del contexto, proteger tus cuotas diarias de API mediante caché y funcionar de manera confiable sin interrumpir tus flujos de trabajo.

¿Por Qué Elegir Este Servidor?

La mayoría de los servidores MCP son proyectos de fin de semana. @kirbah/mcp-youtube está construido para flujos de trabajo agénticos diarios, confiables y rentables.

🎯 ¿Quieres retroalimentación sobre tu propio canal, no solo datos brutos? Consulta CreatorLens: una habilidad de Claude complementaria construida sobre este MCP que diagnostica problemas comunes de crecimiento (ganchos débiles, miniaturas malas, videos estancados) utilizando el marco de trabajo de un estratega real, no solo números.

📉 1. Ahorra Hasta un 87% en Tokens (y Ventana de Contexto)

La API bruta de YouTube devuelve cargas JSON masivas llenas de eTags anidados, miniaturas redundantes y datos de localización que los LLM no necesitan. Este servidor estructura los datos para darle a tu LLM exactamente lo que necesita para razonar, y nada más.

%%{init: { "theme": "base", "themeVariables": { "xyChart": { "plotColorPalette": "#ef4444, #22c55e" } } } }%%
xychart-beta
    title "Token Consumption (Lower is Better)"
    x-axis ["getVideoDetails", "searchVideos", "getChannelStats"]
    y-axis "Context Tokens" 0 --> 1200
    bar "Raw YouTube API" [854, 1115, 673]
    bar "MCP-YouTube (Optimized)" [209, 402, 86]

Método de API	Tokens brutos de YouTube	Tokens de MCP-YouTube	Ahorro de tokens	Tamaño de datos
`getChannelStatistics`	673	86	~87% Menos	1.9 KB ➔ 0.2 KB
`getVideoDetails`	854	209	~75% Menos	2.9 KB ➔ 0.6 KB
`searchVideos`	1115	402	~64% Menos	3.4 KB ➔ 1.2 KB

(¿Curioso? Puedes comparar las respuestas brutas de la API vs. salidas optimizadas en la carpeta de ejemplos).

🛡️ 2. Protege Tus Cuotas de API (Caché Inteligente)

La API de datos de YouTube tiene límites diarios estrictos (10,000 unidades de cuota). Si tu LLM se queda atrapado en un bucle o vuelve a hacer una pregunta, los servidores estándar agotarán tu límite de API en minutos. Este servidor incluye una capa de caché de MongoDB opcional. Si tu agente solicita detalles de un video o busca los mismos videos de tendencia dos veces, el servidor los sirve desde la caché, lo que te cuesta 0 puntos de cuota de API.

🏗️ 3. Calidad Profesional y Mantenimiento Activo

¿Cansado de que las herramientas MCP bloqueen tu cliente de IA? Este servidor está construido para ser una dependencia sólida como una roca:

97% de Cobertura de Pruebas: Probado exhaustivamente a nivel de unidad (consulta la insignia de Codecov).
Cero Errores/Advertencias de Lint: Aplica código estricto y limpio (npm run lint pasa al 100%).
Seguridad Activa: El parcheo automatizado de Dependabot garantiza que las bibliotecas subyacentes nunca queden con vulnerabilidades conocidas.
Seguridad de Tipos Estricta: Construido con validación Zod y la arquitectura robusta de MCP TypeScript Starter.

Inicio Rápido: Instalación

🟢 Modo de Configuración Cero (Sin Clave de API)

¿Solo quieres obtener transcripciones? Puedes usar este servidor de inmediato sin configuración. Solo instala y listo. Agrega una clave de API de YouTube más adelante para desbloquear búsqueda profunda y análisis.

La forma más fácil de instalar este servidor es haciendo clic en el botón "Agregar a Claude Desktop" en la página del servidor en Glama.

Si estás configurando manualmente (por ejemplo, en Cursor), solo agrega esta configuración mínima:

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "@kirbah/mcp-youtube"]
    }
  }
}

✨ Consejo: En el modo de configuración cero, puedes pedirle a tu IA que simplemente "lea la transcripción de youtube://transcript/{videoId}".

🟡 Configuración Manual (Desbloquea Todas las Funciones)

Si prefieres configurar tu cliente MCP manualmente (por ejemplo, Claude Desktop o Cursor), agrega lo siguiente a tu archivo de configuración:

Obtén una clave de YouTube Data API v3 (consulta las Instrucciones de Configuración a continuación).
(Muy recomendado) Obtén una cadena de conexión gratuita de MongoDB para habilitar la caché que ahorra cuota.

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "@kirbah/mcp-youtube"],
      "env": {
        "YOUTUBE_API_KEY": "YOUR_YOUTUBE_API_KEY_HERE",
        "MDB_MCP_CONNECTION_STRING": "mongodb+srv://user:pass@cluster0.abc.mongodb.net/youtube_niche_analysis"
      }
    }
  }
}

(Usuarios de Windows PowerShell: si npx falla, intenta usar "command": "cmd" y "args": ["/k", "npx", "-y", "@kirbah/mcp-youtube"])

Siguiente Paso: Agregar una Habilidad

Una vez que tu servidor esté conectado, prueba CreatorLens: una habilidad de Claude construida específicamente para este MCP que convierte los datos brutos de YouTube en diagnósticos de crecimiento (ganchos débiles, empaque, dudas de nicho, cambios de formato).

Características Clave

Información de Video Optimizada: Busca videos con filtros avanzados. Recupera metadatos detallados, estadísticas (vistas, me gusta, etc.) y detalles de contenido, todo estructurado para un consumo mínimo de tokens.
Gestión Eficiente de Transcripciones: Obtén subtítulos de videos con soporte multilingüe, perfecto para el análisis de contenido por LLMs.
Análisis Perspicaz de Canales: Obtén estadísticas concisas del canal (suscriptores, vistas, número de videos) y descubre los videos de mejor rendimiento de un canal sin exceso de datos.
Descubrimiento Ágil de Tendencias: Encuentra videos de tendencia por región y categoría, y obtén listas de categorías de video disponibles, optimizadas para un procesamiento rápido por IA.
Estructurado para IA: Todas las respuestas están diseñadas para ser fácilmente analizables e inmediatamente útiles para modelos de lenguaje.
Recuperación Eficiente de Comentarios: Obtén comentarios de videos con control fino sobre el número de resultados y respuestas, optimizado para análisis de sentimiento y extracción de retroalimentación.

Herramientas Disponibles

El servidor proporciona las siguientes herramientas MCP, cada una diseñada para devolver datos optimizados en tokens:

Nombre de la Herramienta	Descripción	Parámetros (consulta los detalles en el esquema de la herramienta)
`getVideoDetails`	Recupera información reducida y detallada de múltiples videos de YouTube, incluyendo metadatos, estadísticas, ratios de participación y detalles de contenido.	`videoIds` (matriz de cadenas)
`searchVideos`	Busca videos o canales basándose en una cadena de consulta con varias opciones de filtrado, devolviendo resultados concisos.	`query` (cadena), `maxResults` (número opcional), `order` (opcional), `type` (opcional), `channelId` (opcional), etc.
`getTranscripts`	Recupera transcripciones eficientes en tokens (subtítulos) de múltiples videos, con opciones para texto completo o segmentos clave (intro/outro).	`videoIds` (matriz de cadenas), `lang` (cadena opcional para código de idioma), `format` (enum opcional: 'full_text', 'key_segments' - predeterminado 'key_segments')
`getChannelStatistics`	Recupera estadísticas reducidas de múltiples canales (número de suscriptores, número de vistas, número de videos, fecha de creación).	`channelIds` (matriz de cadenas)
`getChannelTopVideos`	Recupera una lista de los videos de mejor rendimiento de un canal con detalles reducidos y ratios de participación.	`channelId` (cadena), `maxResults` (número opcional)
`getTrendingVideos`	Recupera una lista de videos de tendencia para una región determinada y categoría opcional, con detalles reducidos y ratios de participación.	`regionCode` (cadena opcional), `categoryId` (cadena opcional), `maxResults` (número opcional)
`getVideoCategories`	Recupera las categorías de video de YouTube disponibles (ID y título) para una región específica, proporcionando solo datos esenciales.	`regionCode` (cadena opcional)
`getVideoComments`	Recupera comentarios de un video de YouTube. Permite ordenar, limitar resultados y obtener un pequeño número de respuestas por comentario.	`videoId` (cadena), `maxResults` (número opcional), `order` (opcional), `maxReplies` (número opcional), `commentDetail` (cadena opcional)
`findConsistentOutlierChannels`	Identifica canales que consistentemente rinden como valores atípicos dentro de un nicho específico. Requiere una conexión a MongoDB.	`niche` (cadena), `minVideos` (número opcional), `maxChannels` (número opcional)

Para conocer los parámetros de entrada detallados y sus descripciones, consulta el inputSchema dentro del archivo de configuración de cada herramienta en el directorio src/tools/ (por ejemplo, src/tools/video/getVideoDetails.ts).

Nota sobre los costos de cuota de API: La mayoría de las herramientas son muy eficientes. getVideoDetails, getChannelStatistics y getTrendingVideos cuestan solo 1 unidad por llamada. La herramienta getTranscripts tiene un costo de API de 0. La nueva herramienta getVideoComments tiene un costo variable: la llamada base es de 1 unidad, pero si solicitas respuestas (configurando maxReplies > 0), cuesta 1 unidad adicional por cada comentario de nivel superior del que obtenga respuestas. Las herramientas basadas en búsqueda son las más costosas: searchVideos cuesta 100 unidades y getChannelTopVideos cuesta 101 unidades.

Uso Avanzado y Desarrollo Local

Si deseas contribuir, modificar el servidor o ejecutarlo localmente fuera del entorno gestionado de un cliente MCP:

Requisitos Previos

Node.js (versión especificada en el campo engines de package.json; actualmente >=22.0.0)
npm (normalmente viene con Node.js)
Una clave de YouTube Data API v3 (consulta Configuración de la API de YouTube)

Configuración Local

Clona el repositorio:

git clone https://github.com/kirbah/mcp-youtube.git
cd mcp-youtube

Instala las dependencias:
```
npm ci
```

Configura el entorno: Crea un archivo .env en la raíz copiando .env.example:

cp .env.example .env

Luego, edita .env para agregar tu YOUTUBE_API_KEY:

YOUTUBE_API_KEY=your_youtube_api_key_here
MDB_MCP_CONNECTION_STRING=your_mongodb_connection_string_here

Scripts de Desarrollo

# Run in development mode with live reloading
npm run dev

# Build for production
npm run build

# Run the production build (after npm run build)
npm start

# Lint files
npm run lint

# Run tests
npm run test
npm run test -- --coverage # To generate coverage reports

# Inspect MCP server using the Model Context Protocol Inspector
npm run inspector

Desarrollo Local con un Cliente MCP

Para que un cliente MCP ejecute tu versión de desarrollo local (en lugar del paquete NPM publicado):

Asegúrate de tener un script en package.json para un inicio sin modo de observación, por ejemplo:
```
"scripts": {
  "start:client": "tsx ./src/index.ts"
}
```
Configura tu cliente MCP para ejecutar este script local:
```
{
  "mcpServers": {
    "youtube_local_dev": {
      "command": "npm",
      "args": ["run", "start:client"],
      "working_directory": "/absolute/path/to/your/cloned/mcp-youtube",
      "env": {
        "YOUTUBE_API_KEY": "YOUR_LOCAL_DEV_API_KEY_HERE"
      }
    }
  }
}
```
Nota sobre el bloque env anterior: configurar YOUTUBE_API_KEY directamente en el bloque env para la configuración del cliente es una forma de proporcionar la clave de API. Alternativamente, si tu servidor carga correctamente su archivo .env según el working_directory, es posible que no necesites especificarlo en el bloque env del cliente, siempre que tu archivo .env local en la raíz del proyecto contenga YOUTUBE_API_KEY. La ruta de working_directory debe ser absoluta y correcta para que el servidor encuentre su archivo .env.

Configuración de la API de YouTube

Ve a la Consola de Google Cloud.
Crea un proyecto nuevo o selecciona uno existente.
En el menú de navegación, ve a "APIs y servicios" > "Biblioteca".
Busca "YouTube Data API v3" y Habilítala para tu proyecto.
Ve a "APIs y servicios" > "Credenciales".
Haz clic en "+ CREAR CREDENCIALES" y elige "Clave de API".
Copia la clave de API generada. Esta es tu YOUTUBE_API_KEY.
Paso de seguridad importante: Restringe tu clave de API para evitar usos no autorizados. Haz clic en el nombre de la clave de API y, en "Restricciones de API", selecciona "Restringir clave" y elige "YouTube Data API v3". También puedes agregar "Restricciones de aplicación" (por ejemplo, direcciones IP) si corresponde.

Requisitos del sistema

Node.js: >=22.0.0 (según lo especificado en package.json)
npm (para gestionar dependencias y ejecutar scripts)

Análisis detallado: Herramienta `findConsistentOutlierChannels`

La herramienta findConsistentOutlierChannels está diseñada para identificar canales de YouTube emergentes o consolidados que superan consistentemente su tamaño dentro de un nicho específico. Esta herramienta es especialmente útil para creadores de contenido, especialistas en marketing y analistas que buscan canales de alto potencial.

Nota importante: Esta herramienta requiere una conexión a MongoDB para almacenar y analizar datos de canales. Sin MDB_MCP_CONNECTION_STRING configurado, esta herramienta no estará disponible.

Resumen de la lógica interna

La herramienta opera mediante un proceso de análisis en múltiples fases, aprovechando tanto la API de datos de YouTube como una base de datos MongoDB:

Búsqueda de candidatos (Fase 1):
- Utiliza el query proporcionado para buscar videos y canales relevantes en YouTube.
- Filtra los resultados iniciales según videoCategoryId y regionCode si se especifican.
- Recopila un conjunto amplio de canales potenciales para un análisis más profundo.
Filtrado de canales (Fase 2):
- Recupera estadísticas detalladas de los canales candidatos (suscriptores, vistas totales, número de videos).
- Filtra los canales según channelAge (por ejemplo, 'NUEVO' para canales con menos de 6 meses, 'CONSOLIDADO' para 6-24 meses).
- Garantiza que los canales cumplan con un número mínimo de videos para ser considerados en la consistencia.
Análisis profundo (Fase 3):
- Para cada canal filtrado, obtiene sus videos recientes de mejor rendimiento.
- Calcula un "factor viral" para cada video (por ejemplo, vistas en relación con el número de suscriptores).
- Evalúa el consistencyLevel (por ejemplo, 'MODERADO' para ~30% de videos con rendimiento atípico, 'ALTO' para ~50%).
- Determina outlierMagnitude (por ejemplo, 'ESTÁNDAR' para vistas > suscriptores, 'FUERTE' para vistas > 3x suscriptores).
Clasificación y formato (Fase 4):
- Clasifica los canales según su consistencia, magnitud de valores atípicos y rendimiento general dentro del nicho.
- Formatea los resultados en una estructura optimizada para tokens, adecuada para LLMs, incluyendo métricas clave del canal y ejemplos de videos atípicos.

Parámetros clave que controlan el flujo

El comportamiento de esta herramienta está controlado principalmente por los siguientes parámetros:

query (cadena, obligatorio): El tema o nicho central a analizar (por ejemplo, "reparaciones del hogar DIY", "computación cuántica explicada").
channelAge (enumeración: "NUEVO", "CONSOLIDADO", predeterminado: "NUEVO"): Enfoca la búsqueda en canales emergentes o más maduros.
consistencyLevel (enumeración: "MODERADO", "ALTO", predeterminado: "MODERADO"): Establece el umbral de cuán consistentemente los videos de un canal deben comportarse como valores atípicos.
outlierMagnitude (enumeración: "ESTÁNDAR", "FUERTE", predeterminado: "ESTÁNDAR"): Define cuán significativamente el rendimiento de un video debe superar las expectativas típicas (por ejemplo, vistas vs. suscriptores) para considerarse un "valor atípico".
videoCategoryId (cadena, opcional): Limita la búsqueda a un ID de categoría específico de YouTube.
regionCode (cadena, opcional): Apunta a canales relevantes para una región geográfica particular.
maxResults (número, predeterminado: 10): Limita el número de canales atípicos principales devueltos.

Consideraciones de seguridad

Seguridad de la clave de API: Tu YOUTUBE_API_KEY es sensible. Nunca la confirmes directamente en tu repositorio. Usa variables de entorno (por ejemplo, mediante un archivo .env que debe estar listado en .gitignore).
Cuotas de API: La API de datos de YouTube tiene una cuota de uso diario (el valor predeterminado es 10,000 unidades). Todas las llamadas de herramientas descuentan de esta cuota. Supervisa tu uso en la Consola de Google Cloud y ten en cuenta el costo de cada herramienta. Para un desglose detallado de los costos por método de API, consulta la documentación oficial.
Validación de entrada: El servidor utiliza Zod para una validación robusta de entradas en todos los parámetros de las herramientas, mejorando la seguridad y la confiabilidad.

Licencia

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