youtube-kit

youtube-kit

CLI de YouTube (ytk) y servidor MCP, creado para agentes y humanos. Permite que Claude Code, Codex, Cursor, Claude Desktop o ChatGPT trabajen en tu canal: análisis, subidas, metadatos, listas de reproducción y moderación de comentarios. Maneja varios canales, y puedes ejecutar los mismos comandos en tu propia terminal.

Inicio rápido

uv tool install youtube-kit
ytk auth login      # one-time Google Cloud setup, then pick your channel

Necesitas una cuenta de Google con un canal de YouTube y uv (brew install uv en macOS). La primera ytk auth login tarda unos 5 minutos: abre cada página de Google Cloud, indica qué hacer clic y recoge el archivo que descargas.

ytk analytics --by video --since 90d --limit 5     # your top videos of the last 90 days
ytk comment list --status held                     # comments waiting for review
ytk channel get @mkbhd | jq .stats                 # any public channel

O pregúntale a tu agente: "¿Cuál de mis videos obtuvo más vistas este mes, y hay comentarios esperando revisión?"

Úsalo desde tu agente

Habilidad: Claude Code, Codex, Cursor y otros agentes de shell

Una habilidad breve enseña al agente la CLI. Se carga solo cuando surge una tarea de YouTube.

claude plugin install youtube-kit --marketplace eukosh/youtube-kit   # Claude Code
codex plugin marketplace add eukosh/youtube-kit                      # Codex, then:
codex plugin add youtube-kit@youtube-kit
npx skills add eukosh/youtube-kit -g                                 # Cursor and others

Los complementos siguen las versiones de ytk. Codex los actualiza al iniciar; Claude Code lo hace una vez que activas la actualización automática en /plugin → Marketplaces. Con npx skills, ejecuta npx skills update.

MCP: Claude Desktop, ChatGPT y otros clientes MCP

ytk mcp ofrece las mismas operaciones como herramientas. En Claude Code:

claude mcp add youtube -- uvx youtube-kit mcp

En clientes configurados con JSON (Claude Desktop, Cursor y otros):

{
  "mcpServers": {
    "youtube": { "command": "uvx", "args": ["youtube-kit", "mcp"] }
  }
}

En la aplicación de escritorio de ChatGPT: Configuración → Servidores MCP → Añadir servidor → STDIO, con el comando uvx youtube-kit mcp. Codex comparte esa configuración (codex mcp add youtube -- uvx youtube-kit mcp).

El servidor usa tus inicios de sesión de ytk auth login. Si también instalaste ytk con uv tool install, uvx ejecuta esa versión instalada: uv tool upgrade youtube-kit actualiza ambos. ¿Aún no está configurado? El modelo puede guiarte con la herramienta setup_guide.

Qué cubre

Área	Operaciones
Análisis	totales, o desgloses por día, mes, video, país, dispositivo, sistema operativo, fuente de tráfico, ubicación de reproducción, edad, género o estado de suscripción
Videos	obtener, categorías, subir (reanudable, con progreso), actualizar metadatos, establecer miniatura, esperar procesamiento, dar me gusta o no me gusta, ver tu calificación, eliminar
Comentarios	listar (publicados, en revisión, posible spam), respuestas, publicar, responder, editar, eliminar, aprobar, retener, rechazar, banear al autor
Listas de reproducción	listar, obtener, elementos, crear, actualizar, establecer imagen, añadir, quitar, mover, eliminar
Canal	obtener, actividad reciente, tus canales con sesión iniciada, información (descripción, palabras clave, país, idioma, tráiler), banner, marca de agua, secciones de la página de inicio
Búsqueda	videos, canales y listas de reproducción, filtrados por canal o fecha
Suscripciones	listar, suscribirse, cancelar suscripción

No cubierto: subtítulos, localizaciones, transmisiones en vivo y membresías de canal. ytk --help lista cada comando, y la habilidad los encaja en una página con recetas de jq.

Canales e inicio de sesión

ytk auth login conecta un canal. Ejecútalo de nuevo para cada uno de tus otros canales, incluidos los de marca: elige el que quieras cuando Google lo pregunte.

ytk channel mine                                           # your channels; one is the default
ytk auth switch @second                                    # change the default
ytk video upload clip.mp4 --title Hi --my-channel @third   # use another channel for one command
ytk auth logout @third

Los comandos funcionan en el canal predeterminado a menos que --my-channel nombre otro, por ID UC…, @handle o título exacto. Las herramientas MCP aceptan my_channel de la misma manera, así que puedes decir "sube esto a mi canal de juegos". YOUTUBE_CHANNEL establece el predeterminado para un shell o un servidor MCP.

Por qué tu propio cliente de Google Cloud. La cuota diaria de YouTube de 10,000 unidades pertenece a un proyecto de Cloud. Un cliente incluido dentro de ytk dividiría una cuota entre todos sus usuarios. La tuya es compartida solo por tus canales.

Deja que un agente lo configure. ytk auth guide (setup_guide a través de MCP) lista lo que falta, con enlaces y los valores a ingresar. Con la CLI de gcloud con sesión iniciada, el agente puede crear el proyecto y habilitar las API por ti. El resto necesita tu navegador. ¿Ya tienes el JSON del cliente? Ejecuta ytk auth login --client-secrets FILE.

Configuración manual, archivos y variables de entorno

La configuración guiada hace esto:

1. En la Consola de Google Cloud, crea un proyecto y habilita YouTube Data API v3 y YouTube Analytics API.
2. En Plataforma de autenticación de Google, haz clic en Comenzar (audiencia Externa). En Marca, completa la página de inicio (https://github.com/eukosh/youtube-kit), el enlace de política de privacidad (https://github.com/eukosh/youtube-kit/blob/main/PRIVACY.md) y el dominio autorizado github.com; Google no publicará sin ellos. Luego, en Audiencia, haz clic en Publicar aplicación. Mientras la aplicación esté en Pruebas, solo los usuarios de prueba listados pueden iniciar sesión y Google los cierra después de 7 días.
3. En Clientes, crea un cliente de tipo Aplicación de escritorio y descarga su JSON.
4. ytk auth login --client-secrets path/to/client_secret.json. Google advierte que no ha verificado la aplicación: es tuya, así que haz clic en Avanzado y luego en Ir a ytk (no seguro).

Los datos públicos (búsqueda, videos, canales, listas de reproducción, comentarios) también funcionan solo con una clave de API: créala en el mismo proyecto y export YOUTUBE_API_KEY=..., o colócala en el env del servidor MCP. Sin una clave, ytk lee datos públicos a través de tu inicio de sesión.

ytk recuerda el handle de cada canal desde que iniciaste sesión. Después de renombrar un canal en YouTube, nómbralo por su ID UC… o ejecuta ytk auth login de nuevo para él.

Las credenciales y config.toml viven en el directorio de configuración del usuario (~/Library/Application Support/youtube-kit/ en macOS, ~/.config/youtube-kit/ en Linux). ytk auth status imprime las rutas exactas. Estas variables de entorno las anulan:

Variable	Propósito
YOUTUBE_API_KEY	Clave de API para datos públicos
YOUTUBE_CLIENT_SECRETS	Ruta al JSON del cliente OAuth
YOUTUBE_TOKEN_DIR	Directorio de inicios de sesión almacenados, un archivo por canal
YOUTUBE_CHANNEL	Canal en el que trabajar por defecto (ID UC…, @handle o título exacto), anulando ytk auth switch
YOUTUBE_CONFIG_FILE	Ruta a config.toml (límites de eliminación)

Diseñado para agentes

• Salida JSON, códigos de salida para fallos. Cada comando imprime un documento JSON en stdout. En caso de fallo, stdout permanece vacío, la última línea de stderr es {"error": {"type": "not_found", "message": "..."}}, y el código de salida nombra el tipo: 2 entrada incorrecta, 3 no encontrado, 4 no autorizado, 5 cuota excedida, 6 prohibido, 7 red, 8 confirmación requerida, 9 protegido, 10 tiempo agotado, 1 cualquier otra cosa. La habilidad dice a los agentes qué hacer con cada uno. En una terminal obtienes JSON coloreado y errores en frases simples.
• Entradas tolerantes. Pasa IDs o URLs de YouTube pegadas, @handles para canales, y fechas o rangos como 90d.
• Costos de cuota por adelantado. El --help de cada comando y cada descripción de herramienta MCP indica cuánto gasta.
• Un núcleo. La CLI y el servidor MCP son capas delgadas sobre el mismo código, y una prueba falla si alguno omite una operación.
• Eliminaciones protegidas. Ver abajo.

Eliminación

YouTube no tiene papelera, y los agentes cometen errores. Por eso, eliminar videos, listas de reproducción y comentarios está protegido:

• Dos pasos. La primera llamada no elimina nada. En una terminal obtienes un mensaje de [y/N]. Un agente obtiene salida 8 con una descripción del objetivo y debe ejecutar el comando de nuevo con --confirm <id>, para que la aprobación siempre nombre exactamente lo que se elimina.

• Límite de daño. Un video con más de 100 vistas, o uno que sea público y se haya subido hace más de 7 días, no se puede eliminar aquí en absoluto (salida 9). Elimina esos en YouTube Studio. Los límites viven en config.toml (ytk auth status muestra dónde):

  [delete_protection]
  max_views = 100
  max_public_age_days = 7
  

• Aprobación del arnés. Haz que tu agente te pregunte antes de cada eliminación. En Claude Code, añade esto a .claude/settings.json:

  {"permissions": {"ask": ["Bash(ytk video delete:*)", "Bash(ytk playlist delete:*)", "Bash(ytk comment delete:*)"]}}
  

• Idempotente. Eliminar algo que ya no existe tiene éxito con "already_gone": true.

Esto detiene errores, no a un agente decidido. Cualquier cosa que tenga tu token OAuth puede llamar a la API directamente.

Cuota

Google da a cada proyecto de Cloud 10,000 unidades al día, restableciéndose a medianoche hora del Pacífico. Las lecturas cuestan 1 unidad por solicitud, search 100 por página de 50 resultados, la mayoría de las escrituras 50, eliminaciones protegidas 52 (buscan el objetivo y verifican la propiedad primero), y una subida 1,600. ytk analytics usa la cuota separada de la API de YouTube Analytics.

Contribuciones

Consulta CONTRIBUTING.md para la configuración de desarrollo y CHANGELOG.md para lo que cambió. Reporta problemas de seguridad de forma privada, como describe SECURITY.md.

Licencia

MIT. youtube-kit no está afiliado ni respaldado por Google o YouTube. YouTube es una marca comercial de Google LLC.