YouTube MCP Server

Un servidor de Model Context Protocol (MCP) de código abierto para usar YouTube desde clientes MCP como Claude Desktop, Claude Code y Codex.

El flujo de trabajo principal es:

1. Entregar a un cliente MCP una lista de canciones.

2. Revisar las coincidencias de YouTube clasificadas antes de cambiar nada.

3. Crear una lista de reproducción privada a partir de los vídeos seleccionados.

El servidor también proporcionará herramientas conscientes de la cuota para buscar en YouTube y leer vídeos, canales, listas de reproducción y comentarios.

[!IMPORTANT] El paquete TypeScript, el servidor stdio, las lecturas públicas y autenticadas, OAuth PKCE, la preparación de música, la creación confirmada de nuevas listas de reproducción y las mutaciones completas de listas de reproducción previsualizadas están implementados y probados. Un borrador de música preparado puede confirmarse en una lista de reproducción nueva o añadirse a una lista de reproducción existente de tu propiedad.

Objetivos de diseño

• Escrituras seguras en listas de reproducción con semántica de previsualización antes de confirmar.

• Solo endpoints oficiales de YouTube Data API v3.

• Trae tu propio cliente OAuth de Google; el proyecto nunca incluye credenciales compartidas de Google.

• Secretos almacenados en el llavero del sistema operativo siempre que sea posible.

• Uso predecible de la cuota, paginación, caché, reintentos y errores normalizados.

• Transporte local stdio para una instalación sencilla y una superficie de ataque reducida.

• Salidas de herramientas estructuradas y acotadas que tratan el contenido de YouTube como datos no confiables.

• Soporte TypeScript multiplataforma en Node.js 20.17 o superior.

Related MCP server: youtube-music-mcp

Alcance planificado para v1

Herramientas de lectura

• Buscar vídeos, canales y listas de reproducción.

• Leer datos de vídeos, canales, listas de reproducción y comentarios.

• Leer el canal, las subidas y las listas de reproducción del usuario autenticado.

• Devolver tokens de paginación del proveedor para una paginación explícita y sin estado.

Flujo de trabajo de listas de reproducción de música

• Aceptar hasta 50 pistas estructuradas por solicitud de preparación.

• Buscar y clasificar posibles coincidencias de vídeos musicales de YouTube.

• Mostrar ambigüedad y alternativas en lugar de elegir silenciosamente coincidencias débiles.

• Confirmar explícitamente las coincidencias seleccionadas en una lista de reproducción nueva o en una existente de tu propiedad.

• Las listas de reproducción nuevas son private por defecto.

Gestión de comentarios

• Publicar un comentario de nivel superior en un vídeo, o responder a un comentario existente.

• Eliminar un comentario, o establecer su estado de moderación, tras una previsualización y un identificador de un solo uso.

• Usa el alcance youtube.force-ssl ya solicitado para las escrituras en listas de reproducción, por lo que no se necesita consentimiento adicional.

Gestión de listas de reproducción

• Crear listas de reproducción y añadir vídeos.

• Actualizar metadatos o privacidad de listas de reproducción.

• Reordenar o eliminar elementos de listas de reproducción.

• Eliminar listas de reproducción después de emitir un identificador de confirmación de un solo uso y corta duración.

Las actualizaciones de listas de reproducción, la eliminación/reordenación de elementos y la eliminación usan dos herramientas: youtube_prepare_playlist_mutation devuelve el diff exacto y un identificador de 10 minutos sin escribir; youtube_apply_playlist_mutation vuelve a comprobar la propiedad y la instantánea de la lista de reproducción antes de consumir ese identificador una sola vez.

Subida de vídeos y ciclo de vida

• Subir un archivo de vídeo local mediante una subida reanudable, con private como valor predeterminado.

• Actualizar título, descripción, etiquetas o privacidad de un vídeo de tu propiedad. Los campos no especificados se conservan en lugar de borrarse.

• Establecer una miniatura personalizada desde un JPEG o PNG local.

• Previsualizar y luego eliminar permanentemente un vídeo de tu propiedad.

Las escrituras de vídeo requieren el alcance adicional youtube.upload y se rechazan rotundamente cuando un perfil fue autorizado sin él. youtube_plan_video_upload valida el archivo e informa del coste sin contactar con YouTube, porque videos.insert cuesta 1600 unidades, aproximadamente el 16 % de un presupuesto diario predeterminado por subida. Una subida nunca se reintenta: si el resultado es desconocido, se informa de ello para que puedas comprobar si hay una subida parcial en lugar de publicar un duplicado.

La gestión de listas de reproducción, comentarios y vídeos son las superficies de escritura implementadas. Los informes de analítica (0.8) están en la hoja de ruta y aún no se pueden invocar. Las valoraciones, las suscripciones y las escrituras de ajustes de canal siguen permanentemente fuera del alcance.

Configuración

El paquete npm aún no se ha publicado, por lo que el servidor se compila y ejecuta desde un clon. Sigue los pasos en orden.

Paso 1 — comprueba Node.js y npm

node -v
npm -v

Si node -v imprime v20.17 o superior y npm -v imprime una versión, salta al Paso 3. Si alguno de los dos comandos informa de "command not found", continúa con el Paso 2.

Paso 2 — instala Node.js y npm (solo si el Paso 1 falló)

npm se incluye con Node.js; instalar Node instala ambos. Elige una fila para tu plataforma y vuelve a ejecutar el Paso 1 para confirmarlo.

Si prefieres no instalar Node en todo el sistema, o necesitas varias versiones de Node en paralelo, usa un gestor de versiones:

# macOS and Linux
curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install 22
nvm use 22

En Windows el equivalente es nvm-windows: nvm install 22 y luego nvm use 22.

Cierra y vuelve a abrir la terminal después de instalar y vuelve a ejecutar node -v y npm -v.

Paso 3 — instala las dependencias y compila

git clone <repository-url>
cd "Youtube MCP"
npm ci
npm run build

npm ci instala las versiones exactas de package-lock.json; usa npm install solo cuando tengas intención de cambiar dependencias. La compilación escribe el ejecutable en dist/cli/index.js, que invoca cada uno de los comandos siguientes.

Verifica la compilación y el directorio de datos local:

node dist/cli/index.js doctor

Paso 4 — crea las credenciales de Google

Todo lo siguiente proviene de tu propio proyecto de Google Cloud. Este proyecto nunca incluye credenciales compartidas de Google.

1. Crea o selecciona un proyecto en la consola de Google Cloud.

2. Habilita YouTube Data API v3 para ese proyecto.

3. Crea una clave de API (Credenciales → Crear credenciales → Clave de API). Esto cubre las lecturas públicas.

4. Configura la pantalla de consentimiento de OAuth. Mientras el proyecto esté en estado Testing, añade tu propia cuenta de Google en Usuarios de prueba; de lo contrario, login será rechazado.

5. Crea un cliente OAuth de tipo Aplicación de escritorio y copia tanto su ID de cliente como su secreto de cliente.

Google requiere client_secret en el intercambio del código de autorización incluso para aplicaciones instaladas, por lo que PKCE complementa el secreto aquí en lugar de reemplazarlo.

Paso 5 — las credenciales que necesita el servidor

Existen cuatro credenciales en total. Tú proporcionas las tres primeras; la cuarta la obtiene login por ti.

Variables de entorno opcionales: YOUTUBE_MCP_PROFILE (por defecto default), YOUTUBE_MCP_DATA_DIR y YOUTUBE_MCP_LOG_LEVEL (error, warn, info, debug). Consulta .env.example.

Nunca pegues ninguna de estas en un mensaje de chat, en un archivo de configuración MCP compartido o en un comando que vaya a confirmarse. Prefiere los prompts interactivos o el campo de inyección de secretos/entorno de tu cliente.

Paso 6 — ejecuta setup y luego inicia sesión

Ejecuta estos en orden. setup reescribe los alcances almacenados del perfil y la identidad del canal, por lo que ejecutarlo después de login descarta ese estado y requiere iniciar sesión de nuevo.

macOS y Linux:

YOUTUBE_OAUTH_CLIENT_ID="YOUR_DESKTOP_CLIENT_ID" \
  YOUTUBE_OAUTH_CLIENT_SECRET="YOUR_DESKTOP_CLIENT_SECRET" \
  node dist/cli/index.js setup
node dist/cli/index.js login
node dist/cli/index.js status

Windows PowerShell:

$env:YOUTUBE_OAUTH_CLIENT_ID  = "YOUR_DESKTOP_CLIENT_ID"
$env:YOUTUBE_OAUTH_CLIENT_SECRET = "YOUR_DESKTOP_CLIENT_SECRET"
node dist\cli\index.js setup
node dist\cli\index.js login
node dist\cli\index.js status
Remove-Item Env:\YOUTUBE_OAUTH_CLIENT_SECRET

Para evitar poner el secreto en el historial del shell o en la tabla de procesos, omite ambas variables y deja que setup las solicite:

node dist/cli/index.js setup

setup solicita cada valor que falte cuando la terminal es interactiva.

login abre la página de autorización de Google y regresa a través de un puerto loopback aleatorio en 127.0.0.1, usando PKCE S256 y un valor de estado aleatorio. Falla inmediatamente, antes de abrir un navegador, cuando no hay ningún secreto de cliente almacenado para el perfil.

Para revocar y eliminar la credencial almacenada:

node dist/cli/index.js logout

Paso 7 — inicia el servidor

YOUTUBE_API_KEY="your-api-key" node dist/cli/index.js serve

El servidor habla MCP a través de stdio, por lo que normalmente lo lanza un cliente en lugar de ejecutarse manualmente. Los comandos disponibles son serve, doctor, status, setup, login y logout.

Ubicación de los datos locales

Los perfiles, el registro de cuota, los borradores y los diarios de operaciones viven en un directorio 0700:

Se puede anular con YOUTUBE_MCP_DATA_DIR. Para eliminar todo el estado local, ejecuta logout y luego borra ese directorio. Las entradas del llavero se eliminan con logout.

Conectar un cliente a la compilación local

Hasta que el paquete se publique, apunta los clientes a la ruta absoluta de tu dist/cli/index.js compilado.

Claude Code

claude mcp add youtube --scope user \
  --env YOUTUBE_MCP_PROFILE=default \
  --env YOUTUBE_API_KEY=your-api-key -- \
  node /absolute/path/to/Youtube\ MCP/dist/cli/index.js serve

Claude Desktop

{
  "mcpServers": {
    "youtube": {
      "command": "node",
      "args": ["/absolute/path/to/Youtube MCP/dist/cli/index.js", "serve"],
      "env": {
        "YOUTUBE_MCP_PROFILE": "default",
        "YOUTUBE_API_KEY": "your-api-key"
      }
    }
  }
}

Codex

[mcp_servers.youtube]
command = "node"
args = ["/absolute/path/to/Youtube MCP/dist/cli/index.js", "serve"]

[mcp_servers.youtube.env]
YOUTUBE_MCP_PROFILE = "default"
YOUTUBE_API_KEY = "your-api-key"

Vuelve a ejecutar npm run build después de extraer cambios; los clientes ejecutan la salida compilada de dist, no src.

La autorización de Google para este servidor local la realizan sus propios comandos setup y login. Los comandos de inicio de sesión MCP a nivel de cliente no reemplazan el flujo OAuth de Google posterior.

Configuración del cliente tras la publicación

Una vez publicado el paquete, fija una versión publicada en lugar de usar latest para que un cliente MCP no pueda cambiar el comportamiento inesperadamente.

Claude Desktop

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "@youtube-mcp/server@0.7.0", "serve"],
      "env": {
        "YOUTUBE_MCP_PROFILE": "default"
      }
    }
  }
}

En Windows nativo, usa "command": "cmd" y antepone los argumentos con "/c", "npx".

Claude Code

claude mcp add youtube --scope user \
  --env YOUTUBE_MCP_PROFILE=default -- \
  npx -y @youtube-mcp/server@0.7.0 serve

Codex

codex mcp add youtube \
  --env YOUTUBE_MCP_PROFILE=default -- \
  npx -y @youtube-mcp/server@0.7.0 serve

Configuración equivalente de Codex:

[mcp_servers.youtube]
command = "npx"
args = ["-y", "@youtube-mcp/server@0.7.0", "serve"]

[mcp_servers.youtube.env]
YOUTUBE_MCP_PROFILE = "default"

Cuánto se puede añadir de una vez

Límites estrictos del esquema por llamada a herramienta:

Así que 50 canciones es el techo para una sola confirmación. Una lista más larga se gestiona confirmando en lotes de 50: crea la lista de reproducción con el primer lote y, a continuación, pasa su target_playlist_id en cada confirmación posterior para añadir contenido. Los duplicados ya presentes se omiten y se notifican en lugar de insertarse dos veces.

La cuota diaria es la restricción más ajustada en la práctica. Frente a las 10 000 unidades predeterminadas de Google por proyecto y día, una ejecución de 50 canciones cuesta aproximadamente:

Eso significa aproximadamente una lista de reproducción de 50 canciones por proyecto y día. Una segunda ejecución completa el mismo día agotará la cuota y fallará a mitad de la inserción. Preparar la misma lista dos veces es especialmente costoso: las búsquedas se cobran de nuevo aunque las respuestas no hayan cambiado.

La cuota se restablece a medianoche, hora del Pacífico de EE. UU., que es el límite diario que utiliza el registro local.

Expectativas sobre la cuota

youtube_quota_status informa del uso observado localmente, no de un saldo oficial de Google. Las unidades generales y las llamadas a search.list se registran por separado porque Google aplica un límite diario de llamadas de búsqueda predeterminado distinto.

search.list se factura a sus 100 unidades publicadas, por lo que general_units refleja el consumo real. Las versiones anteriores a la 0.5.0 lo registraban como 1 unidad y, por tanto, subestimaban el uso en 99 unidades por búsqueda; una escritura podía ser rechazada por cuota mientras la cifra notificada seguía pareciendo baja. Actualiza si estás en una compilación anterior.

Los valores de cuota pueden cambiar. El trabajo de implementación y de versiones debe verificar la tabla de costes oficial actual en lugar de tratar los valores de este README como constantes permanentes.

Solución de problemas

Una confirmación informa de status: "partial" con completed vacío y todo en pending. La lista de reproducción se creó, pero la primera inserción fue rechazada — casi siempre por la cuota diaria. No se reintenta nada a ciegas, por lo que no se escriben elementos duplicados. Comprueba youtube_quota_status, elimina la lista de reproducción vacía y vuelve a ejecutar después del restablecimiento de la hora del Pacífico. Como un borrador es de un solo uso, volver a ejecutar requiere un youtube_prepare_music_playlist nuevo.

login falla antes de que se abra un navegador. No hay ningún secreto de cliente almacenado para el perfil. Ejecuta setup primero y confirma que estás en el YOUTUBE_MCP_PROFILE previsto.

La autorización se realiza correctamente, pero deja de funcionar aproximadamente una semana después. Los proyectos de OAuth de Google que permanecen en estado de prueba emiten tokens de actualización que caducan a los siete días. Publica la pantalla de consentimiento o vuelve a ejecutar login.

403 en una lectura pública. Falta YOUTUBE_API_KEY en el entorno del servidor. Nunca se persiste, por lo que debe estar presente en cada inicio — incluido el bloque env de la configuración del cliente MCP.

Modelo de autenticación

• Las lecturas públicas requieren YOUTUBE_API_KEY en el entorno del proceso.

• Las lecturas de cuenta requieren OAuth con el ámbito youtube.readonly.

• La creación de listas de reproducción y las escrituras de comentarios requieren youtube.force-ssl porque Google no proporciona un ámbito exclusivo para listas de reproducción.

• La subida de vídeos y su ciclo de vida requieren youtube.upload. Se solicita por separado, y las herramientas de vídeo se niegan a funcionar cuando un perfil se autorizó sin él. Añádelo a tu pantalla de consentimiento y vuelve a ejecutar login antes de subir.

• El servidor contrarresta ese ámbito amplio de Google con una lista de permitidos estricta de endpoints: solo se pueden invocar los endpoints de escritura de listas de reproducción y de elementos de listas de reproducción.

• Las aplicaciones instaladas usan Código de Autorización + PKCE, un state aleatorio y una redirección de bucle local en 127.0.0.1 con un puerto aleatorio.

• Las cuentas de servicio no son compatibles con las cuentas de YouTube ordinarias.

Nunca confirmes claves de API, datos de cliente OAuth, tokens de acceso, tokens de actualización, bases de datos locales, registros de depuración ni archivos .env.

Subtítulos y analíticas

La recuperación general de transcripciones públicas no forma parte de v1. El endpoint oficial de descarga de subtítulos está restringido por permisos y es costoso, por lo que no se utilizará el raspado no oficial. La gestión de subtítulos autorizada por el propietario podría considerarse más adelante.

Las API de YouTube Analytics y Reporting también se posponen. Requieren OAuth, modelos de datos y comportamiento operativo separados, y no deberían complicar el servidor inicial centrado en listas de reproducción.

Desarrollo

La pila implementada es TypeScript, Node.js 20.17+, ESM, el SDK oficial de TypeScript de MCP, validación con Zod, llamadas REST tipadas directas a los endpoints aprobados de Google, SQLite para el estado local de cuota/borrador/registro y un adaptador de llavero del sistema operativo para los tokens de actualización de OAuth.

Comprobaciones actuales:

npm run format:check
npm run lint
npm run typecheck
npm test
npm run build

La implementación debe seguir las fases y las puertas de aceptación de PLAN.md. Las restricciones específicas del agente y las definiciones de "hecho" están en AGENTS.md. Claude Code debe comenzar con CLAUDE.md.

Estado del proyecto

• Arquitectura de producto y seguridad

• Instrucciones de desarrollo del repositorio

• Andamiaje del paquete TypeScript

• Herramientas de lectura pública

• OAuth y perfiles

• Coincidencia de música y vista previa

• Creación confirmada de nuevas listas de reproducción

• Actualización, reordenación, eliminación y borrado de listas de reproducción con vista previa

• Destino de lista de reproducción existente para confirmaciones de borradores de música (0.5)

• Contabilidad correcta de unidades generales de search.list en el registro de cuota (0.5)

• Inserción, respuesta, eliminación y moderación de comentarios (0.6)

• Subida de vídeos, actualización de metadatos, eliminación y miniaturas (0.7)

• Informes de YouTube Analytics (0.8)

• Pruebas de integración entre clientes

• Primera publicación en npm

Licencia

Licenciado bajo la Licencia Apache 2.0. El texto completo de la licencia está en LICENSE.

Referencias

• Model Context Protocol

• YouTube Data API v3

• Costes de cuota de YouTube Data API

• OAuth de Google para aplicaciones instaladas

• Documentación de MCP de Claude

• Documentación de MCP de Codex