Servidor MCP de YouTube

Servidor MCP de YouTube adaptado basado en el repositorio original claude-code-youtube-mcp. Esta versión admite tanto transporte STDIO como Streamable HTTP, por lo que puede ejecutarse localmente para Claude Code o desplegarse de forma remota para un conector personalizado de Claude.ai.

El servidor proporciona herramientas de la API de datos de YouTube v3 para búsqueda de videos, metadatos, información de canales, listas de reproducción, comentarios, videos en tendencia, análisis de participación, transcripciones, capítulos, limpieza de SponsorBlock y mapas de calor de reproducción más frecuente.

Adaptado de: https://github.com/wynandw87/claude-code-youtube-mcp

Ejecutar localmente

npm install
npm run build
npm run start:http

Endpoints:

GET  /health
POST /mcp

Related MCP server: YouTube MCP Server

Variable de entorno

YOUTUBE_API_KEY=your_key_here

No comprometas tu clave de API en GitHub. Mantenla en tu entorno local, .env o en las variables de entorno de la plataforma de despliegue.

Despliegue en Railway

1. Despliega este repositorio de GitHub en Railway.

2. Agrega la variable de entorno YOUTUBE_API_KEY en Railway.

3. Establece el comando de inicio como:

npm run start:http

4. Usa el endpoint MCP público:

https://your-domain/mcp

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 API de datos de YouTube v3:

   • Ve a Biblioteca de API

   • Haz clic en Habilitar

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+ - Descargar aquí

• CLI de Claude Code - 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 Regístrate con Claude Code

Elige tu alcance de instalación:

Reemplaza YOUR_API_KEY con tu clave real de la API de datos de YouTube 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á configurada 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 listado con un estado de Conectado.

Características

Transcripciones y subtítulos

• Obtener transcripción (get_transcript) - Obtén transcripciones completas de videos con marcas de tiempo, admite varios idiomas

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

• Transcripción limpia (get_clean_transcript) - Transcripción con patrocinadores, intros, outros y relleno eliminados mediante SponsorBlock

• Extraer capítulos (extract_chapters) - Analiza las marcas de tiempo de los capítulos de las descripciones de los videos

Búsqueda y descubrimiento

• Buscar videos (search_videos) - Búsqueda completa de YouTube con filtros por fecha, duración, tipo y orden de clasificación

• Buscar dentro del canal (search_within_channel) - Busca videos de un creador específico

• Obtener videos en tendencia (get_trending_videos) - Videos actualmente en tendencia por región y categoría

• Obtener videos del canal (get_channel_videos) - Subidas recientes de un canal, ordenadas por fecha o vistas

Información de video y canal

• Metadatos del video (get_video_metadata) - Título, descripción, duración, vistas, me gusta, etiquetas y más

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

• Elementos de la lista de reproducción (get_playlist_items) - Todos los videos en una lista de reproducción con posiciones y metadatos

Análisis y participación

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

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

• Comentarios del video (get_video_comments) - Comentarios principales con recuentos de me gusta y respuestas

Utilidades

• Analizar URL de YouTube (parse_youtube_url) - Extrae ID de video/canal/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:

O pregunta de forma natural:

• "Obtén la transcripción de este video de YouTube y resúmela"

• "¿Cuáles son las partes más reproducidas de este video?"

• "Encuentra videos recientes sobre TypeScript en este canal"

• "¿Cuántas vistas y me gusta tiene este video?"

• "Obtén los comentarios de este video y resume el sentimiento"

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

• "Obtén una transcripción limpia sin las lecturas de patrocinadores"

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

Referencia de herramientas

parse_youtube_url

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

Parámetros:

• url (cadena, obligatorio) - Cualquier URL de YouTube o ID de video

Formatos admitidos: youtube.com/watch?v=, youtu.be/, /shorts/, /embed/, /playlist?list=, /channel/, /@handle, /c/, /user/, ID de video sin formato

get_transcript

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

Parámetros:

• url (cadena, obligatorio) - URL de video de YouTube o ID de video

• lang (cadena, opcional) - Código de idioma para subtítulos (predeterminado: "en")

search_transcript

Busca dentro de la transcripción de un video una palabra clave o frase.

Parámetros:

• url (cadena, obligatorio) - URL de video de YouTube o ID de video

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

• lang (cadena, opcional) - Código de idioma para subtítulos (predeterminado: "en")

extract_chapters

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

Parámetros:

• url (cadena, obligatorio) - URL de video de YouTube o ID de video

get_clean_transcript

Obtén la transcripción con lecturas de patrocinadores, intros, outros y relleno eliminados mediante SponsorBlock.

Parámetros:

• url (cadena, obligatorio) - URL de video de YouTube o ID de video

• lang (cadena, opcional) - Código de idioma para subtítulos (predeterminado: "en")

get_most_replayed

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

Parámetros:

• url (cadena, obligatorio) - URL de video de YouTube o ID de video

Nota: Se requieren aproximadamente 50 000+ vistas para que los datos del 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 (predeterminado: 10)

• order (cadena, opcional) - "relevance", "date", "viewCount", "rating" (predeterminado: "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" (predeterminado: "video")

get_video_metadata

Obtén metadatos detallados de un video de YouTube.

Parámetros:

• url (cadena, obligatorio) - URL de video de YouTube o ID de video

Devuelve: Título, descripción, canal, duración, recuentos de vistas/me gusta/comentarios, etiquetas, categoría, miniaturas, estado de transmisión en vivo y más.

get_channel_info

Obtén información del canal de YouTube.

Parámetros:

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

Devuelve: Título, descripción, recuentos de suscriptores/videos/vistas, país, URL personalizada y miniatura.

get_playlist_items

Obtén todos los videos en una lista de reproducción de YouTube.

Parámetros:

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

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

get_channel_videos

Obtén videos 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 videos, 1-50 (predeterminado: 25)

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

get_trending_videos

Obtén videos actualmente en tendencia/populares de YouTube.

Parámetros:

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

• category_id (cadena, opcional) - ID de categoría de YouTube (por ejemplo, "10" para Música, "20" para Juegos, "28" para Ciencia y Tecnología)

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

search_within_channel

Busca videos 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 (predeterminado: 10)

get_video_comments

Obtén comentarios de nivel superior de un video de YouTube.

Parámetros:

• url (cadena, obligatorio) - URL de video de YouTube o ID de video

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

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

calculate_engagement

Calcula métricas de participación para un video de YouTube.

Parámetros:

• url (cadena, obligatorio) - URL de video de YouTube o ID de video

Devuelve: Recuento de vistas, recuento de me gusta, recuento de comentarios, tasa de me gusta, tasa de comentarios y tasa de participación general.

Cómo funciona

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

Nota: 5 herramientas funcionan sin clave de API (transcripciones, SponsorBlock, mapas de calor, análisis 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 diferente:

Consejo: Las operaciones de búsqueda son las más caras. 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 introdujiste una clave de API incorrecta, elimínala y vuelve a instalarla:

claude mcp remove youtube

Luego vuelve a instalarlo usando el comando del Paso 3.3 anterior (usa el mismo alcance 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. Verifica que tu clave de API sea válida en Google Cloud Console

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

   • Ve a API Library

   • Debería decir "Habilitada"

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 exista — 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 excedida

Si ves errores de "quotaExceeded":

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

• Usa una clave de API diferente

• Prefiere herramientas de bajo costo (get_video_metadata a 1 unidad) sobre las herramientas de búsqueda (100 unidades)

Transcripción no disponible

Algunos videos tienen transcripciones deshabilitadas. La herramienta get_transcript devolverá un mensaje de error claro. Prueba:

• Un código de idioma diferente (por ejemplo, lang: "es")

• Los subtítulos generados automáticamente pueden estar disponibles incluso si los manuales no lo están

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 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