YouTube MCP Connector for Claude.ai

Servidor MCP remoto de producción que permite a Claude.ai usar herramientas de solo lectura de YouTube a través de HTTPS:

• search_videos

• get_trending_videos

• get_channel_videos

• get_video_details

• get_engagement_stats

• get_transcript

• search_transcript

El servicio utiliza la YouTube Data API v3 oficial para búsquedas, metadatos, tendencias y subidas de canales. La recuperación de transcripciones es de mejor esfuerzo: primero intenta con las pistas de subtítulos públicas de InnerTube y luego con la detección de subtítulos de la página de visualización de YouTube. No elude CAPTCHA, bloqueos ni límites de velocidad.

Configuración local

npm install
cp .env.example .env

Configura como mínimo:

YOUTUBE_API_KEY=your_google_api_key
AUTH_MODE=none

Ejecuta localmente:

npm run dev

Comprobaciones de salud:

curl http://localhost:3000/health
curl http://localhost:3000/ready

Compila y prueba:

npm test
npm run build

Related MCP server: YouTube MCP Server

Entorno de producción

Variables mínimas de prueba en Railway:

YOUTUBE_API_KEY=...
AUTH_MODE=none

Se recomienda Redis, pero la aplicación puede arrancar sin él y utilizará una caché no operativa en proceso.

Variables completas de producción:

NODE_ENV=production
YOUTUBE_API_KEY=...
AUTH_MODE=oauth
AUTH_ISSUER=https://YOUR_AUTH0_DOMAIN/
AUTH_AUDIENCE=https://youtube-claude-mcp
AUTH_JWKS_URL=https://YOUR_AUTH0_DOMAIN/.well-known/jwks.json
AUTH_REQUIRED_SCOPE=youtube:read
REDIS_URL=...

TTL de caché predeterminados:

TRANSCRIPT_CACHE_TTL_SECONDS=604800
VIDEO_DETAILS_CACHE_TTL_SECONDS=900
TRENDING_CACHE_TTL_SECONDS=600
CHANNEL_VIDEOS_CACHE_TTL_SECONDS=600

Configuración de Auth0

1. Crea o reutiliza una API de Auth0.

2. Establece el identificador de la API con el mismo valor que AUTH_AUDIENCE.

3. Añade el alcance youtube:read.

4. Usa la URL del emisor de Auth0 como AUTH_ISSUER.

5. Usa el endpoint JWKS del tenant como AUTH_JWKS_URL.

6. Configura los ajustes avanzados de OAuth del conector personalizado de Claude.ai con los detalles del cliente de Auth0 correspondientes.

El endpoint /mcp requiere un Authorization: Bearer <token> válido cuando AUTH_MODE=oauth.

Despliegue en Railway

1. Sube el repositorio a GitHub.

2. Crea un proyecto de Railway a partir del repositorio de GitHub.

3. Railway debería usar el Dockerfile incluido en el repositorio mediante railway.json.

4. Añade las variables de servicio:

YOUTUBE_API_KEY=...
AUTH_MODE=none

5. Despliega y abre /health.

6. Añade Redis de Railway más tarde si quieres caché compartida y luego establece REDIS_URL.

7. Cambia a Auth0 estableciendo AUTH_MODE=oauth y las variables de Auth0.

Despliegue en Render

1. Crea una instancia de Redis en Render.

2. Crea un Web Service de Render a partir de este repositorio.

3. Selecciona el despliegue con Docker.

4. Añade las variables de entorno de producción.

5. Despliega.

6. Verifica:

curl https://YOUR_RENDER_URL/health
curl https://YOUR_RENDER_URL/ready
curl -i https://YOUR_RENDER_URL/mcp

El acceso no autenticado a /mcp debería devolver 401.

Conector de Claude.ai

1. Abre la configuración de Claude.ai.

2. Ve a Personalizar y luego a Conectores.

3. Añade un conector personalizado.

4. Usa:

https://YOUR_RENDER_URL/mcp

5. Configura los ajustes avanzados de OAuth si la autenticación de producción está activada.

6. Habilita el conector en un chat.

Indicaciones de demostración:

• Busca en YouTube 5 tutoriales recientes de servidores MCP.

• ¿Cuáles son los vídeos más populares en Pakistán ahora mismo?

• Muestra los últimos vídeos de @GoogleDevelopers.

• Obtén visualizaciones, me gusta y duración para esta URL de YouTube.

• Calcula su tasa de interacción.

• Obtén la transcripción y resúmela.

• ¿Dónde mencionan la autenticación en la transcripción?

Notas operativas

• Restringe y rota la clave de API de YouTube en Google Cloud cuando sea práctico.

• No registres claves de API, tokens de portador ni cabeceras de autorización completas.

• Las llamadas de búsqueda consumen mucha cuota; prefiere las subidas de canales y los metadatos en caché siempre que sea posible.

• Los fallos de Redis degradan el comportamiento de la caché, pero no hacen fallar las llamadas normales a las herramientas.

• Los fallos de transcripción pueden ocurrir cuando los subtítulos están desactivados, no disponibles, restringidos por región o bloqueados por YouTube.

• Las respuestas de CAPTCHA o de bloqueo de bots se muestran como errores; el servicio no intenta evadirlos.

Solución de problemas

• El inicio falla con YOUTUBE_API_KEY is required: establece la clave de API del servidor.

• El inicio falla en producción con REDIS_URL is required: conecta Redis de Render y establece su URL.

• /mcp devuelve 401: el token falta, ha expirado, está mal formado o está firmado por un emisor incorrecto.

• /mcp devuelve 403: el token es válido pero carece de youtube:read.

• La herramienta de transcripción devuelve no disponible: es posible que el vídeo no tenga subtítulos públicos.

• Cuota de YouTube superada: espera a que se restablezca la cuota, solicita un aumento de cuota o reduce el uso de búsquedas.