maagpi-youtube-mcp

maagpi-youtube-mcp

maagpi-youtube-mcp es un servidor MCP completo de gestión de canales de YouTube: sube vídeos, programa publicaciones, consulta analíticas, modera comentarios, gestiona listas de reproducción, actualiza la marca del canal y opera múltiples canales de YouTube simultáneamente — todo desde cualquier cliente de IA compatible con MCP.

Envuelve la YouTube Data API v3 oficial + la YouTube Analytics API detrás de una única superficie MCP con OAuth integrado, seguimiento de cuota, caché de respuestas y gestión estructurada de errores.

Transporte

• Predeterminado: stdio (proceso local, iniciado por tu cliente MCP)
• Opcional: Streamable HTTP (YOUTUBE_MCP_TRANSPORT=http) para acceso multi-cliente / remoto
• Distribución: npx maagpi-youtube-mcp — no se requiere instalación global
• Documentación completa: consulta Referencia de herramientas a continuación

Autenticación

Este servidor usa Google OAuth 2.0 (credenciales de aplicación de escritorio). Proporcionas un ID de cliente + Secreto de cliente como variables de entorno; el servidor gestiona el flujo de consentimiento del navegador y almacena tokens de actualización en el directorio de configuración de tu SO bajo perfiles con nombre (uno por canal).

Configuración única de Google Cloud

1. Google Cloud Console → APIs y Servicios → Biblioteca → habilita:
   • YouTube Data API v3
   • YouTube Analytics API
2. APIs y Servicios → Pantalla de consentimiento de OAuth → Externa → completa el nombre de la aplicación + tu correo electrónico → añade tu cuenta de Google como usuario de prueba.
3. APIs y Servicios → Credenciales → Crear credenciales → ID de cliente de OAuth → Tipo de aplicación Aplicación de escritorio → copia el ID de cliente y el Secreto de cliente.

Mantén tu Secreto de cliente fuera del control de versiones. El servidor nunca lo transmite a ningún sitio excepto accounts.google.com.

Primera llamada: el servidor abre una ventana del navegador para el consentimiento de OAuth. Aprueba una vez y los tokens se guardan automáticamente bajo el perfil "default" y se actualizan automáticamente a partir de entonces. Añade más canales con youtube_account_add.

Conexión rápida

Elige tu cliente y pega el fragmento en el archivo de configuración correspondiente. Reemplaza your_client_id / your_client_secret con tus credenciales de Google OAuth.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) %APPDATA%\Claude\claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "maagpi-youtube-mcp"],
      "env": {
        "YOUTUBE_CLIENT_ID": "your_client_id",
        "YOUTUBE_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Claude Code

~/.claude/settings.json

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "maagpi-youtube-mcp"],
      "env": {
        "YOUTUBE_CLIENT_ID": "your_client_id",
        "YOUTUBE_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

O mediante la CLI de Claude Code:

claude mcp add youtube -- npx -y maagpi-youtube-mcp \
  -e YOUTUBE_CLIENT_ID=your_client_id \
  -e YOUTUBE_CLIENT_SECRET=your_client_secret

Cursor

~/.cursor/mcp.json

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "maagpi-youtube-mcp"],
      "env": {
        "YOUTUBE_CLIENT_ID": "your_client_id",
        "YOUTUBE_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "maagpi-youtube-mcp"],
      "env": {
        "YOUTUBE_CLIENT_ID": "your_client_id",
        "YOUTUBE_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

VS Code (extensiones compatibles con MCP)

.vscode/mcp.json (espacio de trabajo) o Configuración de usuario:

{
  "servers": {
    "youtube": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "maagpi-youtube-mcp"],
      "env": {
        "YOUTUBE_CLIENT_ID": "your_client_id",
        "YOUTUBE_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Zed

~/.config/zed/settings.json

{
  "context_servers": {
    "youtube": {
      "command": {
        "path": "npx",
        "args": ["-y", "maagpi-youtube-mcp"],
        "env": {
          "YOUTUBE_CLIENT_ID": "your_client_id",
          "YOUTUBE_CLIENT_SECRET": "your_client_secret"
        }
      }
    }
  }
}

mcporter

mcporter add youtube --command "npx -y maagpi-youtube-mcp" \
  --env YOUTUBE_CLIENT_ID=your_client_id \
  --env YOUTUBE_CLIENT_SECRET=your_client_secret

mcporter call youtube youtube_account_list '{}'

Streamable HTTP (remoto / multi-cliente)

Ejecuta el servidor como un servicio HTTP:

YOUTUBE_MCP_TRANSPORT=http \
YOUTUBE_MCP_HTTP_PORT=3000 \
YOUTUBE_CLIENT_ID=your_client_id \
YOUTUBE_CLIENT_SECRET=your_client_secret \
npx -y maagpi-youtube-mcp
# MCP endpoint: POST http://127.0.0.1:3000/mcp
# Health check: GET  http://127.0.0.1:3000/health

Luego apunta cualquier cliente MCP compatible con HTTP a http://127.0.0.1:3000/mcp.

Referencia de herramientas

Todas las herramientas aceptan un parámetro opcional channel (nombre de perfil). Omítelo para usar el perfil activo.

Gestión de cuentas

Herramienta	Parámetros	Descripción
youtube_account_add	name	Conecta un nuevo canal mediante OAuth y guárdalo como perfil con nombre
youtube_account_list	ninguno	Lista todos los perfiles conectados con IDs y estado activo
youtube_account_switch	name	Establece el perfil activo predeterminado
youtube_account_current	ninguno	Muestra el perfil actualmente activo
youtube_account_remove	name, confirm: true	Desconecta y elimina un perfil

Vídeos

Herramienta	Parámetros	Cuota
youtube_video_upload	filePath, title, privacyStatus, channel?	1600
youtube_video_get	videoId, parts?, channel?	1
youtube_video_list	channelId?, query?, order?, maxResults?, channel?	1
youtube_video_update	videoId, title?, description?, tags?, channel?	50
youtube_video_delete	videoId, confirm: true, channel?	50
youtube_video_rate	videoId, rating (like/dislike/none), channel?	50
youtube_video_set_thumbnail	videoId, thumbnailPath, channel?	50

Programación y publicación

Herramienta	Parámetros	Cuota
youtube_video_set_privacy	videoId, privacyStatus, channel?	50
youtube_video_schedule_publish	videoId, publishAt (fecha futura ISO 8601), channel?	50
youtube_video_set_premiere	videoId, premiereAt (fecha futura ISO 8601), channel?	50

Analíticas

Herramienta	Parámetros	Cuota
youtube_analytics_video_metrics	videoId, startDate, endDate, metrics[], channel?	1
youtube_analytics_channel_metrics	startDate, endDate, metrics[], channel?	1
youtube_analytics_top_videos	startDate, endDate, metric, maxResults?, channel?	1
youtube_analytics_audience_retention	videoId, startDate, endDate, channel?	1
youtube_analytics_revenue_report	startDate, endDate, dimensions?, channel?	1

Las fechas usan YYYY-MM-DD. Métricas de vídeo comunes: views, watchTime, averageViewDuration, averageViewPercentage, likes, shares, subscribersGained, subscribersLost. Las métricas de canal añaden estimatedRevenue, estimatedAdRevenue, grossRevenue, monetizedPlaybacks, cpm, adImpressions.

Comentarios

Herramienta	Parámetros	Cuota
youtube_comment_list	videoId, maxResults?, order?, searchTerms?, channel?	1
youtube_comment_thread_get	commentThreadId, maxReplies?, channel?	1
youtube_comment_reply	parentCommentId, text, channel?	50
youtube_comment_delete	commentId, channel?	50
youtube_comment_moderate	commentId, moderationStatus (published/heldForReview/rejected), banAuthor?, channel?	50

Listas de reproducción

Herramienta	Parámetros	Cuota
youtube_playlist_create	title, privacyStatus, channel?	50
youtube_playlist_update	playlistId, title?, description?, channel?	50
youtube_playlist_delete	playlistId, confirm: true, channel?	50
youtube_playlist_get	playlistId, channel?	1
youtube_playlist_list	channelId?, maxResults?, channel?	1
youtube_playlist_item_add	playlistId, videoId, position?, channel?	50
youtube_playlist_item_remove	playlistItemId, channel?	50
youtube_playlist_item_reorder	playlistItemId, playlistId, newPosition, channel?	50
youtube_playlist_items_list	playlistId, maxResults?, channel?	1

Gestión de canales

Herramienta	Parámetros	Cuota
youtube_channel_get	parts?, channel?	1
youtube_channel_update	title?, description?, keywords?, country?, channel?	50
youtube_channel_branding_update	showRelatedChannels?, featuredChannelsTitle?, channel?	50
youtube_channel_watermark_set	channelId, imagePath, position, timing, channel?	50
youtube_channel_watermark_unset	channelId, channel?	50
youtube_channel_section_list	channelId?, channel?	1
youtube_channel_section_create	type, title?, playlistIds?, channel?	50
youtube_channel_section_delete	sectionId, channel?	50

Ejemplos de prompts

Una vez conectado, envía estos a tu cliente de IA como lenguaje natural:

Upload /videos/tutorial.mp4 with title "Getting Started with TypeScript",
description "A beginner's guide", tags ["typescript","programming"], unlisted.

Schedule video dQw4w9WgXcQ to go public on January 20 2026 at 3pm UTC.

Get top 5 videos by views in Q1 2025 for my "main" channel,
and also for my "gaming" channel.

Show me revenue breakdown for 2025-01-01 to 2025-01-31, split by day.

Reply to comment Ugxxxxx with "Thanks for the feedback! Fixed in v2."

Las herramientas que eliminan datos requieren confirm: true — tu cliente de IA preguntará antes de continuar.

Múltiples canales

Conecta cualquier número de cuentas de YouTube y apunta a cualquiera de ellas desde cualquier herramienta mediante el parámetro opcional channel — sin necesidad de cambiar.

Add a new YouTube channel profile named "gaming"
List all my connected YouTube channel profiles
Switch my active YouTube profile to "gaming"
Upload /videos/clip.mp4 to my "gaming" channel, title "EP1", public

Autenticación CLI para un perfil con nombre (útil para configuraciones sin interfaz):

npm run auth -- --channel gaming

Cuota

YouTube Data API v3 otorga 10.000 unidades/día por defecto. Cada respuesta de herramienta incluye un campo quota:

{
  "quota": {
    "used": 151,
    "budget": 9000,
    "remaining": 8849,
    "resetAt": "2026-01-15T08:00:00.000Z",
    "warningLevel": "ok",
    "costOfThisCall": 1
  }
}

warningLevel: "ok" → "warn" al 80% → "critical" al 95%.

Protecciones integradas

• Las respuestas GET se almacenan en caché (vídeos 60s, canales 5min, analíticas 5min) — las lecturas repetidas cuestan 0 de cuota
• Las escrituras se reintentan automáticamente en 429/5xx con retroceso exponencial (hasta 3×)
• Establece YOUTUBE_MCP_QUOTA_LIMIT por debajo de 10.000 para dejar margen

Formato de error

Todos los errores se devuelven como contenido estructurado de herramienta — los agentes pueden leerlos y actuar sobre ellos sin fallar:

{
  "success": false,
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "YouTube API daily quota has been exceeded.",
    "suggestedFix": "Wait for quota reset at midnight Pacific Time, or increase your quota in Google Cloud Console.",
    "retryable": false,
    "docsUrl": "https://developers.google.com/youtube/v3/getting-started#quota"
  },
  "quota": { "used": 9001, "warningLevel": "critical" }
}

Código	Significado
AUTH_REQUIRED	No hay tokens almacenados — se necesita el flujo de OAuth
AUTH_TOKEN_EXPIRED	Token caducado y actualización fallida — vuelve a autenticarte
AUTH_INSUFFICIENT_SCOPE	Falta el ámbito de OAuth — elimina los tokens y vuelve a autenticarte
QUOTA_EXCEEDED	Cuota diaria agotada — espera al reinicio de medianoche PT
PERMISSION_DENIED	Recurso no propiedad de la cuenta autenticada
VIDEO_NOT_FOUND	El ID de vídeo no existe o no es accesible
PLAYLIST_NOT_FOUND	ID de lista de reproducción no encontrado
RATE_LIMITED	Límite de velocidad temporal — el servidor reintenta automáticamente
INVALID_PARAMS	Falló la validación de Zod — comprueba los tipos de parámetros
PUBLISH_DATE_IN_PAST	publishAt / premiereAt debe ser una fecha y hora futura

Variables de entorno

Variable	Obligatoria	Predeterminado	Descripción
YOUTUBE_CLIENT_ID	✓	—	ID de cliente de Google OAuth2
YOUTUBE_CLIENT_SECRET	✓	—	Secreto de cliente de Google OAuth2
YOUTUBE_MCP_TRANSPORT		stdio	stdio o http
YOUTUBE_MCP_HTTP_PORT		3000	Puerto del servidor HTTP
YOUTUBE_MCP_HTTP_HOST		127.0.0.1	Dirección de enlace HTTP
YOUTUBE_MCP_QUOTA_LIMIT		9000	Umbral de advertencia de cuota diaria
YOUTUBE_MCP_CACHE_TTL		por recurso	Sobrescribe todos los TTL de caché (ms)
YOUTUBE_MCP_LOG_LEVEL		info	error | warn | info | debug

Desarrollo

npm install
npm run dev          # run with tsx (requires .env)
npm run auth         # authenticate the default channel profile
npm run auth -- --channel gaming   # authenticate a named profile
npm run typecheck    # tsc --noEmit
npm test             # vitest unit tests
npm run build        # production bundle → dist/index.js
npm pack --dry-run   # verify publish artifact

Por qué maagpi-youtube-mcp 🎯

• Opera YouTube desde cualquier cliente de IA — Claude, Cursor, Windsurf, Zed, VS Code, mcporter
• Gestiona múltiples canales a la vez — sin cambio de contexto, apunta a cualquier canal por llamada
• Infraestructura de nivel de producción — OAuth, tokens de actualización, seguimiento de cuota, reintentos, errores estructurados
• Cobertura completa de superficie — vídeos, programación, analíticas, comentarios, listas de reproducción, marca

Enlaces

• npm: https://www.npmjs.com/package/maagpi-youtube-mcp
• YouTube Data API: https://developers.google.com/youtube/v3
• YouTube Analytics API: https://developers.google.com/youtube/analytics
• Model Context Protocol: https://modelcontextprotocol.io