youtube-mcp
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.
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:latestConfiguración: Google Cloud (una sola vez, ~10 min)
Cuenta de Google más canal de YouTube. Usa una cuenta personal, no una de trabajo que podrías perder.
Proyecto de Google Cloud en https://console.cloud.google.com. Llámalo como quieras (p. ej.,
youtube-mcp).Habilitar APIs:
YouTube Data API v3
YouTube Analytics API
Pantalla de consentimiento de OAuth: Externo, nombre de la aplicación, correo electrónico de soporte. En Ámbitos (Scopes), añade:
youtube.uploadyoutube.force-sslyt-analytics.readonly
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á.
Crear ID de cliente de OAuth: Tipo de aplicación = Aplicación de escritorio. Descarga el JSON.
Ejecutar el flujo de autenticación interactivo:
npx @miller-joe/youtube-mcp --auth --client-secret-file ./client_secret.jsonSe 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.Iniciar el servidor:
npx @miller-joe/youtube-mcp --client-secret-file ./client_secret.jsonO proporciona las credenciales del cliente mediante variables de entorno:
YOUTUBE_CLIENT_SECRET_FILE, oYOUTUBE_CLIENT_ID+YOUTUBE_CLIENT_SECRET.
Conectar un cliente MCP
claude mcp add --transport http youtube http://localhost:9120/mcpO apunta tu puerta de enlace MCP al endpoint HTTP Streamable.
Configuración
Flag de CLI | Variable de entorno | Predeterminado | Notas |
|
| (ninguno) | Ruta al JSON de Google OAuth |
|
| (ninguno) | Alternativa al archivo secreto |
|
| (ninguno) | Alternativa al archivo secreto |
|
|
| Almacenamiento del token de actualización |
|
|
| Host de enlace (solo modo HTTP) |
|
|
| Puerto de enlace (solo modo HTTP) |
|
| (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). |
|
| (sin establecer, puente deshabilitado) | URL HTTP de ComfyUI para herramientas de puente |
(sin flag) |
|
| 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 queconfirm_video_titlecoincida 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 testRequiere 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) yget_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:
Available Tools
15 toolsadd_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
Scored across 15 tools
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.
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.
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.
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
Related MCP Connectors
Create and refine AI YouTube thumbnails with the ThumblifyAI MCP server.
An MCP server that gives any LLM or agent clean YouTube transcripts on demand: a single video, a whole channel, or a playlist, plus AI cleanup of auto-generated captions. API-key auth, credit-based, same backend as the public v1 API. Get a free API key with 25 free credits at youtubetranscriptdownload.com/account.
MCP server for Google Veo AI video generation
Hosted MCP for YouTube Studio: uploads, metadata, playlists, comments, analytics, captions.
Related MCP Servers
- FlicenseAqualityDmaintenanceA Model Context Protocol server that enables Claude to interact with YouTube data and functionality through the Claude Desktop application.112-
- FlicenseNot gradedqualityDmaintenanceAn MCP server that enables interaction with the YouTube Data API, allowing users to search videos, get video and channel details, analyze trends, and fetch video transcripts.-
- AlicenseAqualityDmaintenanceMCP server for ComfyUI — text-to-image, variations, img2img refine, upscale, image proxy, and workflow runner.15145 npm3MIT
- AlicenseAqualityBmaintenanceA comprehensive MCP server integrating YouTube Data, Analytics, and Reporting APIs, providing 40 tools for channel management, analytics, video publishing, transcripts, SEO, and comments.4034MIT