yt-playlist-organizer-mcp

Un servidor MCP para organizar listas de reproducción de YouTube mediante la YouTube Data API v3.

Hace exactamente una cosa y nada más: crear, listar, actualizar y eliminar listas de reproducción y sus elementos. No toca videos, canales, subtítulos, comentarios, suscripciones ni ningún otro recurso de la YouTube Data API.

Construido con el @modelcontextprotocol/sdk oficial y los endpoints REST de la YouTube Data API v3 (sin la pesada dependencia de googleapis).

Herramientas

Todo lo que hace este servidor. No hay otras herramientas.

Listas de reproducción (/playlists)

Elementos de lista de reproducción (/playlistItems)

Además, auth_status para comprobar qué credenciales están configuradas.

Related MCP server: youtube-mcp

Configuración

Este servidor solo llama a los endpoints /playlists y /playlistItems. El resto de la YouTube Data API queda fuera del alcance.

El servidor lee dos variables de entorno:

Consulta .env.example.

• Lecturas (..._list) funcionan solo con una clave de API (o un token de acceso).

• Escrituras (insert/update/delete) y mine=true requieren un token de acceso OAuth2 con los ámbitos youtube, youtube.force-ssl o youtubepartner.

Cómo obtener credenciales OAuth2

1. Crea un proyecto en Google Cloud Console.

2. Habilita la YouTube Data API v3.

3. Crea un ID de cliente OAuth2 (aplicación de escritorio) y descarga el JSON.

4. Intercambia las credenciales por un token de acceso (p. ej. mediante google-auth-oauthlib en Python, o un servicio local de flujo OAuth). Establece YOUTUBE_ACCESS_TOKEN=<token>.

5. (Opcional) Crea una clave de API para un uso más sencillo de solo lectura.

Nix

Esto es compatible con NixOS. Se proporcionan tanto un flake como un shell.nix.

# Enter the dev shell (node + typescript toolchain)
nix develop

# or, non-flake:
nix-shell

Compilar

npm install        # install node deps (zod + MCP SDK)
npm run build      # emits dist/
npm run typecheck  # tsc --noEmit

Ejecutar localmente

# Reads only (API key):
YOUTUBE_API_KEY=... node dist/index.js

# Reads + writes/mine (OAuth access token):
YOUTUBE_ACCESS_TOKEN=... node dist/index.js

Integración con opencode

Añade lo siguiente a ~/.config/opencode/opencode.jsonc bajo mcp:

"mcp": {
  "yt-playlist-organizer-mcp": {
    "type": "local",
    "command": ["node", "<path-to-repo>/dist/index.js"],
    "enabled": true,
    "environment": {
      "YOUTUBE_API_KEY": "{file:~/.secrets/yt-api-key}",
      "YOUTUBE_ACCESS_TOKEN": "{file:~/.secrets/yt-access-token}"
    }
  }
}

Reemplaza <path-to-repo> con la ruta absoluta donde lo clonaste, o instálalo mediante npm para ejecutarlo por nombre:

npm install -g .
# then use:  "command": ["yt-playlist-organizer-mcp"]

Para ejecutarlo a través del shell de Nix en su lugar, usa la misma clave pero cambia command:

"command": ["nix", "develop", "<path-to-repo>", "--command", "node", "dist/index.js"],

Notas

• Los costes de cuota se basan en la documentación oficial de la API y se documentan por herramienta.

• Los valores de part se validan contra los conjuntos válidos para cada recurso.

• playlists_list / playlistItems_list requieren exactamente un parámetro de filtro; de lo contrario, la validación de entrada rechaza la llamada.

• Las herramientas de actualización (playlists_update, playlistItems_update) leen primero el recurso existente y conservan cualquier campo omitido (p. ej. description, privacyStatus, position, contentDetails), en lugar de borrarlos. Por lo tanto, cada actualización cuesta una lectura adicional de tu cuota.

• startAt/endAt se proporcionan en segundos y se convierten a duraciones ISO 8601 (PT1M30S) antes de enviarse a la API.

Desarrollo

npm install
npm test         # vitest unit tests
npm run typecheck
npm run build

Licencia

MIT