Skip to main content
Glama

youtube-mcp

MCP de YouTube con autenticación OAuth para propietarios de canales. Edita metadatos de video, responde y modera comentarios, gestiona listas de reproducción, consulta análisis de canales y genera o establece miniaturas mediante 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.

youtube-mcp MCP server

GitHub Sponsors Ko-fi

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 (Código de autorización + PKCE) para que realmente pueda escribir en tu canal: actualizar títulos, descripciones y etiquetas de video, responder comentarios, moderar spam, gestionar listas de reproducción. También accede a la API de YouTube Analytics por separado para estadísticas del canal, y genera una miniatura mediante 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 y los envía mediante POST a thumbnails.set. Listo.

Related MCP server: yt-fetch

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 más canal de YouTube. Usa 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 de OAuth: Externo, nombre de la aplicación, correo electrónico de soporte. En Ámbitos (Scopes), 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 de 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 y concedes los ámbitos solicitados. Si tiene é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 mediante 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

Flag de CLI

Variable de entorno

Predeterminado

Notas

--client-secret-file

YOUTUBE_CLIENT_SECRET_FILE

(ninguno)

Ruta al JSON de Google OAuth

--client-id

YOUTUBE_CLIENT_ID

(ninguno)

Alternativa al archivo secreto

--client-secret

YOUTUBE_CLIENT_SECRET

(ninguno)

Alternativa al archivo secreto

--token-file

YOUTUBE_TOKEN_FILE

~/.config/youtube-mcp/token.json

Almacenamiento del token de actualización

--host

MCP_HOST

0.0.0.0

Host de enlace (solo modo HTTP)

--port

MCP_PORT

9120

Puerto de enlace (solo modo HTTP)

--stdio

MCP_TRANSPORT=stdio

(sin establecer)

Hablar MCP a través de stdio en lugar de HTTP. Úsalo cuando se inicie como subproceso por un cliente MCP que priorice stdio (Claude Desktop, mcp-inspector).

--comfyui-url

COMFYUI_URL

(sin establecer, puente deshabilitado)

URL HTTP de ComfyUI para herramientas de puente

(sin flag)

COMFYUI_DEFAULT_CKPT

sd_xl_base_1.0.safetensors

Punto de control predeterminado para la herramienta de puente

Transportes

El servidor habla HTTP streamable de forma predeterminada (ideal para Claude Code, MetaMCP, fetch sin procesar). Pasa --stdio (o establece MCP_TRANSPORT=stdio) para cambiar al modo stdio, que es lo que esperan los clientes que priorizan stdio como Claude Desktop y el Inspector MCP:

// claude_desktop_config.json
{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "@miller-joe/youtube-mcp", "--stdio"],
      "env": {
        "YOUTUBE_CLIENT_SECRET_FILE": "/path/to/client_secret.json",
        "YOUTUBE_TOKEN_FILE": "/path/to/token.json"
      }
    }
  }
}

El modo Stdio omite la verificación previa del token OAuth: el servidor arranca incluso sin un token almacenado y muestra errores de autenticación en el momento de la llamada a la herramienta. Ejecuta youtube-mcp --auth --client-secret-file <ruta> una vez en modo HTTP para sembrar el token de actualización antes de apuntar Claude Desktop hacia él.

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: eliminar permanentemente un video. Requiere que confirm_video_title coincida exactamente con el título actual, como medida de seguridad contra la eliminación del video incorrecto.

Subtítulos

  • list_captions: listar pistas de subtítulos en un video (idioma, nombre, estado, indicador de borrador).

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

  • delete_caption: eliminar una pista de subtítulos.

Shorts

  • list_my_shorts: encontrar Shorts en 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: crear una lista de reproducción (privada por defecto).

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

Comentarios

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

  • reply_to_comment: responder a un comentario de nivel superior.

  • moderate_comment: retener, aprobar o rechazar un comentario.

Análisis

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

Puente (cuando COMFYUI_URL está configurado)

  • generate_and_set_thumbnail: generar una miniatura mediante ComfyUI y establecerla en un video en una sola llamada.

Notas sobre la cuota

Nivel gratuito de YouTube Data API = 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, por lo que unas 6 subidas al 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 a tiempo antes de que caduquen. La herramienta de puente descarga bytes de imagen de ComfyUI internamente, por lo que 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

Publicado:

  • Videos: listar, obtener, actualizar metadatos, eliminar con protección de confirmación de coincidencia de título.

  • Subtítulos: subir, listar, eliminar.

  • Shorts: list_my_shorts (filtro de duración) y get_shorts_analytics (creatorContentType==SHORTS).

  • Listas de reproducción: crear, añadir a.

  • Comentarios: listar, responder, moderar.

  • Análisis: consulta de análisis de canal.

  • Puente de miniaturas de ComfyUI: generate_and_set_thumbnail.

Planeado:

  • Subida de video (video_upload) con 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:

GitHub Sponsors Ko-fi

Available Tools

15 tools
add_to_playlistB

Add a video to an existing playlist. Both playlist_id and video_id are YouTube IDs (not URLs).

Inputs: playlist_id (required), video_id (required).

create_playlistB

Create a new playlist on the authenticated channel. Default privacy is 'private'.

Inputs: title (required), description, privacy_status.

delete_captionA

Delete a caption track by ID. Use list_captions to find the track ID first.

Inputs: caption_id (required).

delete_videoA

Permanently delete a video. Requires confirm_video_title to match the video's current title exactly — guards against deleting the wrong video by ID. Deletion is irreversible.

Inputs: video_id (required), confirm_video_title (required).

get_shorts_analyticsA

Query YouTube Analytics restricted to Shorts for the authenticated channel. Applies filters=creatorContentType==SHORTS on top of the usual start_date/end_date/metrics/dimensions knobs.

Inputs: start_date (required), end_date (required), metrics, dimensions, +2 more.

get_videoA

Fetch full details for one video by ID — snippet, status, statistics, duration.

Inputs: video_id (required).

list_captionsA

List caption tracks on a video with their language, name, status, and whether they are drafts.

Inputs: video_id (required).

list_commentsB

List top-level comment threads on a video (newest first). Returns comment IDs, authors, text, and like counts.

Inputs: video_id (required), max_results.

list_my_shortsA

List your recent Shorts — scans the most recent uploads and filters to videos ≤60s. Useful when the Data API doesn't expose a direct Shorts filter.

Inputs: max_candidates.

list_my_videosA

List videos on the authenticated channel (newest first via the uploads playlist). Returns video IDs, titles, view counts, and privacy status.

Inputs: max_results, page_token.

moderate_commentA

Change the moderation status of a comment: heldForReview (hide pending approval), published (approve), or rejected (delete).

Inputs: comment_id (required), moderation_status (required).

query_channel_analyticsA

Query YouTube Analytics for the authenticated channel. Returns tabular data — useful for views/watch-time/retention/traffic-source reports. Date-ranged and optionally grouped by dimensions.

Inputs: start_date (required), end_date (required), metrics, dimensions, +3 more.

reply_to_commentB

Reply to a top-level comment. Requires youtube.force-ssl scope.

Inputs: parent_id (required), text (required).

update_video_metadataA

Update a video's metadata — title, description, tags, category, or privacy. Only provide fields you want changed.

Inputs: video_id (required), title, description, tags, +2 more.

upload_captionA

Upload a caption track (SRT or WebVTT) to a video. Creates a new track — use a distinct name per language/track, or is_draft=true while iterating.

Inputs: video_id (required), language (required), caption_text (required), name, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 15 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action. Analytics tools are clearly differentiated (general vs Shorts-specific), and video list vs Shorts list is scoped by content type. Comments, captions, and playlists each have their own dedicated tools with no overlap.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern (list_, get_, create_, update_, delete_, upload_, reply_to_, add_to_, moderate_, query_). There are no mixed conventions or cryptic abbreviations, making the naming predictable and easy to reason about.

    Tool Count5/5

    15 tools cover a broad YouTube management surface without feeling bloated. The set is well-scoped for the server's purpose—video, playlist, caption, comment, and analytics operations—and each tool has a clear role within that scope.

    Completeness3/5

    The coverage has significant gaps, especially for playlists: there is no way to list, retrieve, delete, or remove items from playlists, creating dead ends after creation. Caption updates are also absent (only create and delete), although video CRUD and comment moderation are well covered.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers