youtube-mcp

MCP de YouTube con autenticación OAuth para propietarios de canales: edita los metadatos de tus videos, responde y modera comentarios, gestiona listas de reproducción, consulta estadísticas del canal y genera + establece miniaturas con IA a través de un puente con ComfyUI. Va más allá de los envoltorios de solo lectura de la Data API v3 que dominan este espacio.

Parte de la Serie de Servidores MCP.

La propuesta

La mayoría de los MCP de YouTube existentes utilizan una clave de API contra la Data API v3: buscar videos, obtener metadatos públicos, solo lectura. Este utiliza OAuth 2.0 (Authorization Code + PKCE) para que realmente pueda escribir en tu canal: actualizar títulos/descripciones/etiquetas de videos, responder comentarios, moderar spam, gestionar listas de reproducción. Además, accede a la YouTube Analytics API independiente para estadísticas del canal y, la herramienta estrella, genera una miniatura a través de ComfyUI y la envía a YouTube en una sola llamada MCP.

Claude, use generate_and_set_thumbnail on video abc123:
  prompt: "cyberpunk hacker at keyboard, neon blue and pink, high contrast"

→ ComfyUI renderiza 1280×720 → youtube-mcp obtiene los bytes → hace POST a thumbnails.set. Listo.

Instalación

# npx — no install
npx @miller-joe/youtube-mcp --help

# Docker
docker run -p 9120:9120 \
  -e YOUTUBE_CLIENT_ID=... \
  -e YOUTUBE_CLIENT_SECRET=... \
  -e YOUTUBE_TOKEN_FILE=/token/token.json \
  -v $PWD/token:/token \
  ghcr.io/miller-joe/youtube-mcp:latest

Configuración: Google Cloud (una sola vez, ~10 min)

1. Cuenta de Google + canal de YouTube: utiliza una cuenta personal, no una de trabajo que podrías perder.

2. Proyecto de Google Cloud en https://console.cloud.google.com: llámalo como quieras (p. ej., youtube-mcp).

3. Habilitar APIs:

   • YouTube Data API v3

   • YouTube Analytics API

4. Pantalla de consentimiento OAuth: Externo, nombre de la aplicación, correo electrónico de soporte; en Scopes (ámbitos) añade:

   • youtube.upload

   • youtube.force-ssl

   • yt-analytics.readonly

5. Mantente en modo Prueba. Añádete a ti mismo como usuario de prueba (obligatorio). Como propietario del proyecto, tu token de actualización no caducará.

6. Crear ID de cliente OAuth: Tipo de aplicación = Aplicación de escritorio. Descarga el JSON.

7. Ejecutar el flujo de autenticación interactivo:

   npx @miller-joe/youtube-mcp --auth --client-secret-file ./client_secret.json

   Se abre un navegador → inicias sesión en la cuenta de Google vinculada a tu canal de YouTube → concedes los ámbitos solicitados. Tras el éxito, se guarda un token de actualización en ~/.config/youtube-mcp/token.json.

8. Iniciar el servidor:

   npx @miller-joe/youtube-mcp --client-secret-file ./client_secret.json

   O proporciona las credenciales del cliente a través de variables de entorno: YOUTUBE_CLIENT_SECRET_FILE, o YOUTUBE_CLIENT_ID + YOUTUBE_CLIENT_SECRET.

Conectar un cliente MCP

claude mcp add --transport http youtube http://localhost:9120/mcp

O apunta tu puerta de enlace MCP al endpoint HTTP Streamable.

Configuración

Herramientas

Videos

• list_my_videos: lista paginada de las subidas del canal autenticado

• get_video: detalle completo de un video

• update_video_metadata: título / descripción / etiquetas / categoría / privacidad

• delete_video: elimina permanentemente un video. Requiere que confirm_video_title coincida exactamente con el título actual como medida de seguridad para evitar borrar el video incorrecto.

Subtítulos

• list_captions: lista las pistas de subtítulos de un video (idioma, nombre, estado, indicador de borrador)

• upload_caption: sube una pista de subtítulos SRT o WebVTT a un video

• delete_caption: elimina una pista de subtítulos

Shorts

• list_my_shorts: encuentra Shorts en las subidas recientes (filtra por duración ≤60s)

• get_shorts_analytics: consulta de YouTube Analytics restringida a Shorts (creatorContentType==SHORTS)

Listas de reproducción

• create_playlist: crea una lista de reproducción (privada por defecto)

• add_to_playlist: añade un video a una lista de reproducción existente

Comentarios

• list_comments: hilos de comentarios de nivel superior en un video

• reply_to_comment: responde a un comentario de nivel superior

• moderate_comment: retener / aprobar / rechazar un comentario

Análisis

• query_channel_analytics: métricas por rango de fechas con dimensiones y filtros opcionales

Puente (cuando COMFYUI_URL está configurado)

• generate_and_set_thumbnail: genera una miniatura a través de ComfyUI y la establece en un video en una sola llamada

Notas sobre la cuota

Nivel gratuito de la API de datos de YouTube = 10,000 unidades/día. Costos de operaciones clave:

• videos.list, commentThreads.list: 1 unidad cada una

• videos.update, comments.insert, thumbnails.set: 50 unidades cada una

• videos.insert (subida): 1,600 unidades → ~6 subidas/día en el nivel gratuito

La mayoría de los flujos de trabajo de operaciones de creadores se mantienen muy por debajo del límite gratuito.

Arquitectura

┌────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  MCP client    │────▶│  youtube-mcp     │────▶│  YouTube APIs   │
│  (Claude etc.) │◀────│  (this server)   │◀────│  (Data/Analytics)│
└────────────────┘     └────────┬─────────┘     └─────────────────┘
                                │
                                │ (bridge tools only)
                                ▼
                       ┌──────────────────┐
                       │  ComfyUI         │
                       │  (txt2img)       │
                       └──────────────────┘

Los tokens de actualización de OAuth se almacenan en caché localmente y se actualizan justo antes de que caduquen. La herramienta de puente descarga los bytes de la imagen desde ComfyUI internamente; ComfyUI no necesita ser accesible públicamente.

Desarrollo

git clone https://github.com/miller-joe/youtube-mcp
cd youtube-mcp
npm install
npm run dev
npm run build
npm test

Requiere Node 20+.

Hoja de ruta

• [x] Listar / obtener / actualizar metadatos de video

• [x] Crear / añadir a lista de reproducción

• [x] Listar / responder / moderar comentarios

• [x] Consulta de análisis de canal

• [x] Puente de miniaturas de ComfyUI (generate_and_set_thumbnail)

• [x] Subir / listar / eliminar subtítulos (upload_caption, list_captions, delete_caption)

• [x] Eliminar video con confirmación de coincidencia de título

• [x] Ergonomía de Shorts: list_my_shorts (filtro de duración) + get_shorts_analytics (creatorContentType==SHORTS)

• [ ] Subida de video (video_upload): soporte para subida reanudable

• [ ] API de informes para exportaciones masivas de datos históricos

Licencia

MIT © Joe Miller

Soporte

Si esto te ahorra tiempo, considera apoyar el desarrollo: