YouTube MCP Server

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

El flujo de trabajo principal es:

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

2. Revisa las coincidencias de YouTube clasificadas antes de que se cambie nada.

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

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

[!IMPORTANT] El paquete de 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 con vista previa están implementados y probados. Añadir un borrador de música preparado directamente a una lista de reproducción existente sigue siendo un plan: hoy, las canciones solo se pueden insertar en el momento de crear la lista.

Objetivos de diseño

• Escrituras seguras de listas de reproducción con semántica de vista previa antes de confirmar.

• Solo puntos de conexión oficiales de la API de datos de YouTube v3.

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

• Los secretos se guardan en el llavero del sistema operativo siempre que sea posible.

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

• Transporte stdio local para una instalación sencilla y una superficie de ataque pequeña.

• 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 posterior.

Alcance planificado para v1

Herramientas de lectura

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

• Leer datos de vídeo, canal, lista de reproducción y comentarios.

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

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

Flujo de trabajo de listas de música

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

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

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

• Confirmar las coincidencias seleccionadas explícitamente en una lista de reproducción nueva. Está previsto un destino de lista existente.

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

Gestión de listas de reproducción

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

• Actualizar los metadatos o la privacidad de la lista.

• Reordenar o eliminar elementos de la lista.

• 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, la eliminación/reordenación de elementos y el borrado 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 antes de consumir ese identificador una sola vez.

Las escrituras fuera de la gestión de listas de reproducción (subidas, comentarios, valoraciones, suscripciones y cambios de canal) están deliberadamente fuera del alcance.

Configuración

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

Paso 1: comprobar Node.js y npm

node -v
npm -v

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

Paso 2: instalar Node.js y npm (solo si el Paso 1 falló)

npm se distribuye 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 a la vez, 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 luego vuelve a ejecutar node -v y npm -v.

Paso 3: instalar dependencias y compilar

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 es invocado por todos los comandos siguientes.

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

node dist/cli/index.js doctor

Paso 4: crear las credenciales de Google

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

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 de pruebas, añade tu propia cuenta de Google en Usuarios de prueba; de lo contrario, se rechazará login.

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

Google exige 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

En total existen cuatro credenciales. 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 avisos interactivos o el campo de inyección de secretos/entorno de tu cliente.

Paso 6: ejecuta setup y luego inicia sesión

Ejecuta estos comandos 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 por completo poner el secreto en el historial de la 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 de bucle local aleatorio en 127.0.0.1, usando PKCE S256 y un valor de estado aleatorio. Falla de inmediato, 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: iniciar el servidor

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

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

Ubicación de los datos locales

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

Puedes sobrescribirla con YOUTUBE_MCP_DATA_DIR. Para eliminar todo el estado local, ejecuta logout y luego borra ese directorio. logout elimina las entradas del llavero.

Conexión de un cliente a la compilación local

Hasta que se publique el paquete, 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 en 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 de 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 de forma inesperada.

Claude Desktop

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

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

Claude Code

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

Codex

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

Configuración equivalente para Codex:

[mcp_servers.youtube]
command = "npx"
args = ["-y", "@youtube-mcp/server@0.4.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:

Por lo tanto, 50 canciones es el máximo para la creación de una sola lista de reproducción. Dado que un borrador preparado aún no se puede confirmar en una lista existente, una lista de más de 50 canciones debe convertirse en más de una lista.

En la práctica, la cuota diaria es la restricción más estricta. Con la cuota predeterminada de Google de 10,000 unidades 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 al 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 caro: 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 usa 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 predeterminado y separado para las llamadas de búsqueda.

[!WARNING] Limitación conocida: el registro local contabiliza cada search.list como 1 unidad general más 1 llamada de búsqueda, mientras que Google cobra 100 unidades por dicha llamada. Después de muchas búsquedas, general_units subestima, por lo tanto, el consumo real en 99 unidades por búsqueda, y una escritura puede ser rechazada por superar la cuota mientras que la cifra informada sigue pareciendo baja. Considera el contador de search_calls como la señal significativa hasta que esto se corrija. Las vistas previas siguen mostrando una cifra de estimated_commit_units para la parte de escritura de un commit.

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

Solución de problemas

Un commit devuelve 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. Consulta youtube_quota_status, elimina la lista de reproducción vacía y vuelve a ejecutarlo después del restablecimiento de la hora del Pacífico. Dado que un borrador es de un solo uso, para volver a ejecutarlo se necesita un youtube_prepare_music_playlist nuevo.

login falla antes de que se abra un navegador. No se almacena ningún secreto de cliente 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 OAuth de Google que permanecen en estado de pruebas 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. YOUTUBE_API_KEY no está en el entorno del servidor. Nunca se persiste, por lo que debe estar presente en cada lanzamiento — 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 alcance youtube.readonly.

• La creación de listas de reproducción requiere youtube.force-ssl porque Google no ofrece un alcance exclusivo para listas de reproducción.

• El servidor contrarresta ese amplio alcance de Google con una lista estricta de endpoints permitidos: solo los endpoints de escritura de listas de reproducción y de elementos de listas de reproducción son invocables.

• Las aplicaciones instaladas usan Authorization Code + 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 normales de YouTube.

Nunca hagas commit de 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ítica

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 caro, por lo que no se utilizará el scraping no oficial. La gestión de subtítulos autorizada por el propietario podría considerarse más adelante.

Las APIs 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 tecnológica implementada es TypeScript, Node.js 20.17+, ESM, el SDK oficial de MCP para TypeScript, validación con Zod, llamadas REST tipadas directas a los endpoints aprobados de Google, SQLite para el estado local de cuota, borradores y 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 los controles de aceptación de PLAN.md. Las restricciones específicas de los agentes 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

• Estructura inicial del paquete TypeScript

• Herramientas de lectura pública

• OAuth y perfiles

• Emparejamiento musical 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 previsualizados

• Destino de lista de reproducción existente para commits de borradores de música

• Corregir la contabilización de unidades generales de search.list en el registro de cuota

• Pruebas de integración entre clientes

• Primera publicación en npm

Licencia

Licenciado bajo la Apache License 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

• Google OAuth para aplicaciones instaladas

• Documentación de Claude MCP

• Documentación de Codex MCP