YouTube MCP Server

Servidor MCP que lleva YouTube a Claude Code: transcripciones de vídeo, búsqueda, metadatos, información de canales, listas de reproducción, comentarios, vídeos en tendencia, análisis de interacción, extracción de capítulos, integración con SponsorBlock y mapas de calor de lo más reproducido. Utiliiza la YouTube Data API v3, youtube-transcript y SponsorBlock.

Inicio rápido

Paso 1: Obtén tu clave de API

1. Ve a Google Cloud Console

2. Crea un proyecto (o selecciona uno existente)

3. Habilita la YouTube Data API v3:

   • Ve a Biblioteca de API

   • Haz clic en Habiltar

4. Crea una clave de API:

   • Ve a Credenciales

   • Haz clic en Crear credenciales > Clave de API

5. Copia la clave (la necesitarás en el Paso 3)

Paso 2: Instala los requisitos previos

• Node.js 18+ - Descárgalo aquí

• Claude Code CLI - Guía de instalación

Paso 3: Instala el servidor MCP

3.1 Clona el repositorio

git clone https://github.com/wynandw87/claude-code-youtube-mcp.git
cd claude-code-youtube-mcp

3.2 Instala las dependencias

macOS / Linux / Windows:

npm install

Nota: Las dependencias se instalan y el servidor se compile automáticamente en un solo paso.

3.3 Registra el servidor con Claude Code

Elige el ámbito de instalación:

Reemplaza YOUR_API_KEY con tu clave real de la YouTube Data API y usa la ruta completa hasta dist/index.js.

Consejo: Para obtener la ruta completa, ejecuta esto desde el directorio clonado:

• macOS/Linux: echo "$( pwd)/dist/index.js"

• Windows: echo %cd%\dist\index.js

macOS / Linux:

claude mcp add -s user youtube -e YOUTUBE_API_KEY=YOUR_API_KEY -- node /full/path/to/dist/index.js

Windows (CMD):

claude mcp add -s user youtube -e "YOUTUBE_API_KEY=YOUR_API_KEY" -- node "C:\full\path\to\dist\index.js"

Windows (PowerShell):

claude mcp add -s user youtube -e "YOUTUBE_API_KEY=YOUR_API_KEY" '--' node "C:\full\path\to\dist\index.js"

Alternativa: Utiliza el asistent de npm (si la clave de API está definida en el entorno)

export YOUTUBE_API_KEY=YOUR_API_KEY
npm run install:claude

Paso 4: Reinicia Claude Code

Cierra y vuelve a abrir Claude Code para que los cambios surtan efecto.

Paso 5: Verifica la instalación

claude mcp list

Deberías ver youtube en la lista con estado Conectado.

Related MCP server: youtube-mcp

Funcionalidades

Transcripciones y subtítulos

• Obtener transcripción (get_transcript) - Obtén la transcripción completa del vídeo con marcas de tiempo; admite varos idiomas

• Buscar en la transcripción (search_transcript) - Encuentra dónde aparece una palabra clave o frase en un vídeo con marcas de tiempo

• Transcripción limpia (get_clean_transcript) - Transcripción sin menciones de patrocinadores, intros, outros ni relleno, eliminadas mediante SponsorBlock

• Extrar capítulos (extract_chapters) - Parsea las marcas de tiempo de los capítulos a partir de las descripciones de los vídeos

Búsqueda y descuibrimiento

• Buscar vídeos (search_videos) - Búsqueda completa en YouTube con filtros por fecha, duración, tipo y orden

• Buscar en el canal (search_withia_channel) - Busca vídeos de un creador específico

• Obtener vídeos en tendencia (get_trending_videos) - Vídeos en tendencia actualmente por región y categoría

• Obtener vídeos del canal (get_channel_videos) - Subidas recientes de un canal, ordenadas por fecha o visualizaciones

Información de vídeos y canales

• Metadatos del vídeo (get_video_metadata) - Título, descripción, duración, visualizaciones, me gustas, etiquetas y más

• Información del canal (get_channel_info) - Número de suscriptores, número de vídeos, descripción, país

• Eements de la lista de reproducción (get_playlist_items) - Todos los vídeos de una lista de reproducción con sus posiciones y metadatos

Análisis e interacción

• Calcular interacción (calculate_engagement) - Tasa de me gustas, tasa de comentarios y tasa de interacción a partir de estadísticas públicas

• Lo más reproducido (get_most_replayed) - Datos de mapa de calor que muestran qué partes vuelven a ver más los espectadores

• Comentarios del vídeo (get_video_comments) - Principales comentarios con número de me gustas y respuestas

Utilidades

• Analizar URL de YouTube (parse_youtube_url) - Extrae IDs de vídeo/canal/lista de reproducción de cualqier formato de URL de YouTube

Uso

Una vez instalado, usa frases desencadenantes para invocar las herramientas de YouTube:

O pregunta de forma natural:

• "Obten la transcripción de este vídeo de YouTube y resúmela"

• "¿Cuáles son las partes más reproducidas de este vídeo?"

• "Encuentra vídeos recientes sobre TypeScript en este canal"

• "¿Cuántas visualizaciones y me gustas tiene este vídeo?"

• "Obten los comentarios de este vídeo y resume el sentimiento"

• "Muéstrame los capítulos de este tutorial"

• "Obten una transcripción limpia sin las menciones de patrocinadores"

• "¿Qué está en tendencia en YouTube en videojuegos ahora mismo?"

Referencia de herramientas

parse_youtube_url

Analiza cualquier formato de URL de YouTube y extrae los identificadores. No se necesita clave de API.

Parámetros:

• url (cadena, obligatorio) - Cualquier URL de YouTube o ID de vídeo

Formatos admitidos: youtube.com/watch?v=, youtu.be/, /shorts/, /embed/, /playlist?list=, /channel/, /@handle, /c/, /user/, IDs de vídeo simples

get_transcript

Obtén la transcripción/los subtítulos completos de un vídeo de YouTube. No se necesita clave de API.

Parámetros:

• url (cadena, obligatorio) - URL del vídeo de YouTube o ID de vídeo

• lang (cadena, opcional) - Código de idioma de los subtítulos (por defecto: "en")

search_transcript

Busca dentro de la transcripción de un vídeo una palabra clave o frase.

Parámetros:

• url (cadena, obligatorio) - URL del vídeo de YouTube o ID de vídeo

• query (cadena, obligatorio) - Palabra clave o frase para buscar

• lang (cadena, opcional) - Código de idioma de los subtítulos (por defecto: "en")

extract_chapters

Extrae las marcas de tiempo de los capítulos de la descripción de un vídeo.

Parámetros:

• url (cadena, obligatorio) - URL del vídeo de YouTube o ID de vídeo

get_clean_transcript

Obtén la transcripción sin menciones de patrocinadores, intros, outros ni relleno mediante SponsorBlock.

Parámetros:

• url (cadena, obligatorio) - URL del vídeo de YouTube o ID de vídeo

• lang (cadena, opcional) - Código de idioma de los subtítulos (por defecto: "en")

get_most_replayed

Obtén los datos de mapa de calor de «lo más reproducido» que muestran qué partes vuelven a ver más los espectadores.

Parámetros:

• url (cadena, obligatorio) - URL del vídeo de YouTube o ID de vídeo

Nota: Se requieren aproximadamente 50K+ visualizaciones para que los datos de mapa de calor estén disponibles.

search_videos

Busca en YouTube con soporte completo de filtros.

Parámetros:

• query (cadena, obligatorio) - Consulta de búsqueda

• max_results (número, opcional) - Número de resultados, 1-50 (por defecto: 10)

• order (cadena, opcional) - "relevance", "date", "viewCount", "rating" (por defecto: "relevance")

• duration (cadena, opcional) - "short" (<4 min), "medium" (4-20 min), "long" (>20 min)

• upload_date (cadena, opcional) - "hour", "day", "week", "month", "year"

• type (cadena, opcional) - "video", "channel", "playlist" (por defecto: "video")

get_video_metadata

Obtén metadatos detallados de un vídeo de YouTube.

Parámetros:

• url (cadena, obligatorio) - URL del vídeo de YouTube o ID de vídeo

Devuelve: Título, descripción, canal, duración, número de visualizaciones/me gustas/comentarios, etiquetas, categoría, miniaturas, estado de emisión en directo y más.

get_channel_info

Obtén información de un canal de YouTube.

Parámetros:

• url (cadena, obligatorio) - URL del canal de YouTube, @handle o ID de canal

Devuelve: Título, descripción, número de suscriptores/vídeos/visualizaciones, país, URL personalizada y miniatura.

get_playlist_items

Obtén todos los vídeos de una lista de reproducción de YouTube.

Parámetros:

• url (cadena, obligatorio) - URL de la lista de reproducción de YouTube o ID de la lista

• max_results (número, opcional) - Número de elementos, 1-50 (por defecto: 25)

get_channel_videos

Obtén los vídeos recientes de un canal de YouTube.

Parámetros:

• url (cadena, obligatorio) - URL del canal de YouTube, @handle o ID de canal

• max_results (número, opcional) - Número de vídeos, 1-50 (por defecto: 25)

• order (cadena, opcional) - "date", "viewCount" (por defecto: "date")

get_trending_videos

Obtén los vídeos actualmente en tendencia/populares de YouTube.

Parámetros:

• region_code (cadena, opcional) - Código de país ISO 3166-1 alfa-2 (por defecto: "US")

• category_id (cadena, opcional) - ID de categoría de YouTube (p. ej., "10" para Música, "20" para Videojuegos, "28" para Ciencia y Tecnología)

• max_results (número, opcional) - Número de resultados, 1-50 (por defecto: 10)

search_withia_channel

Busca vídeos dentro de un canal específico de YouTube.

Parámetros:

• url (cadena, obligatorio) - URL del canal de YouTube, @handle o ID de canal

• query (cadena, obligatorio) - Consulta de búsqueda

• max_results (número, opcional) - Número de resultados, 1-50 (por defecto: 10)

get_video_comments

Obtén los comentarios de primer nivel de un vídeo de YouTube.

Parámetros:

• url (cadena, obligatorio) - URL del vídeo de YouTube o ID de vídeo

• max_results (número, opcional) - Número de comentarios, 1-100 (por defecto: 20)

• order (cadena, opcional) - "relevance", "time" (por defecto: "relevance")

calculate_engagement

Calula las métricas de interacción de un vídeo de YouTube.

Parámetros:

• url (cadena, obligatorio) - URL del vídeo de YouTube o ID de vídeo

Devuelve: Número de visualizaciones, número de me gustas, número de comentarios, tasa de me gustas, tasa de comentarios y tasa de interacción general.

Cómo funciona

Este servidor MCP se conecta a Claude Code mediante el transporte stdio y proporciona 15 herramientas:

Nota: 5 herramientas funcionan sin una clave de API (transcripciones, SponsorBlock, mapas de calor, parseo de URL). Las 10 restantes requieren una clave de YouTube Data API v3.

Configuración

Variables de entorno

Cuota de la API de YouTube

La YouTube Data API v3 tiene una cuota diaria de 10.000 unidades. Cada herramienta consume una cantidad diferente:

Consejo: Las operaciones de búsqueda son las más costosas. Usa get_channel_videos (1 unidad) en lugar de search_within_channel (100 unidades) cuando solo necesites las últimas subidas.

Solución de problemas

Corregir la clave de API

Si has introducido una clave de API incorrecta, elimina el servidor y vuelve a instalarlo:

claude mcp remove youtube

Luego reinstálalo usando el comando del Paso 3.3 anterior (usa el mismo ámbito con el que lo instalaste originalmente).

El servidor MCP no aparece

Comprueba si el servidor está instalado:

claude mcp list

Si no aparece, sigue el Paso 3 para instalarlo.

El servidor no se inicia

1. Comprueba que tu clave de API es válida en Google Cloud Console

2. Comprueba que la YouTube Data API está habilitada:

   • Ve a API Library

   • Debería decir «Enabled»

3. Comprueba la versión de Node.js (necesita 18+):

   node --version

4. Asegúrate de que el servidor se haya compilado — si falta dist/index.js, ejecuta npm install de nuevo

Errores de conexión

1. Comprueba que dist/index.js existe — si no es así, ejecuta npm install

2. Verifica que la ruta sea absoluta en tu comando claude mcp add

3. Reinicia Claude Code después de cualquier cambio de configuración

Cuota superada

Si ves errores de «quotaExceeded»:

• Espera hasta la medianoche, hora del Pacífico (la cuota se restablece a diario)

• Usa una clave de API diferente

• Prefiere herramientas de bajo coste (get_video_metadata a 1 unidad) en lugar de herramientas de búsqueda (100 unidades)

Transcripción no disponible

Algunos vídeos tienen las transcripciones desactivadas. La herramienta get_transcript devolverá un mensaje de error claro. Prueba:

• Un código de idioma diferente (p. ej., lang: "es")

• Puede haber subtítulos generados automáticamente incluso si los manuales no están disponibles.

Errores de tiempo de espera

Aumenta la variable de entorno YOUTUBE_TIMEOUT para conexiones lentas:

claude mcp add -s user youtube -e YOUTUBE_API_KEY=YOUR_KEY -e YOUTUBE_TIMEOUT=60000 -- node /path/to/dist/index.js

Ver la configuración actual

claude mcp list

Contribuciones

¡Las pull requests son bienvenidas! Por favor, mantenlo simple y apto para principiantes.

Licencia

MIT

Hecho para la comunidad de Claude Code