YouTube MCP Server

Servidor MCP que integra YouTube en Claude Code — transcripciones de vídeo, búsqueda, metadatos, información de canales, listas de reproducción, comentarios, vídeos en tendencia, métricas de interacción, extracción de capítulos, integración con SponsorBlock y mapas de calor de las partes más reproducidas. Utiliza 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. Activa la YouTube Data API v3:

   • Ve a Biblioteca de API

   • Haz clic en Activar

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 compila automáticamente en un solo paso.

3.3 Registra el servidor con Claude Code

Elige el ámbito de instalación:

Sustituye YOUR_API_KEY por tu clave real de la YouTube Data API y usa la ruta completa a 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: usa el asistente 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 el estado Conectado.

Related MCP server: youtube-research

Funcionalidades

Transcripciones y subtítulos

• Obtener transcripción (get_transcript) - Obtén la transcripción completa del vídeo con marcas de tiempo; admite varios 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 contenido de relleno, eliminados mediante SponsorBlock.

• Extraer capítulos (extract_chapters) - Analiza las marcas de tiempo de los capítulos en las descripciones de los vídeos.

Búsqueda y descubrimiento

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

• Buscar dentro de un canal (search_within_channel) - Busca vídeos de un creador concreto.

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

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

Información de vídeos y canales

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

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

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

Analíticas e interacción

• Calcular interacción (calculate_engagement) - Tasa de «me gusta», 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) - Comentarios principales con número de «me gusta» y número de respuestas.

Utilidades

• Analizar URL de YouTube (parse_youtube_url) - Extrae los IDs de vídeo, canal o lista de reproducción de cualquier formato de URL de YouTube.

Uso

Una vez instalado, usa frases de activación para invocar las herramientas de YouTube:

Nota: 5 herramientas funcionan sin 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 usa una cantidad distinta:

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 subidas recientes.

Solución de problemas

Corregir la clave de API

Si has introducido una clave de API incorrecta, elimina y vuelve a instalar:

claude mcp remove youtube

A continuación, reinstala 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 en la lista, sigue el paso 3 para instalarlo.

El servidor no arranca

1. Verifica 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 indicar "Enabled"

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

   node --version

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

Errores de conexión

1. Comprueba que dist/index.js existe — si no, 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) frente a las 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")

• Es posible que haya subtítulos autogenerados aunque no haya subtítulos manuales

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, manténlo sencillo y apto para principiantes.

Licencia

MIT

Hecho para la comunidad de Claude Code