yt-dlp

🎬 yt-dlp-mcp

✨ Características

🚀 Instalación

Requisitos previos

Instala yt-dlp en tu sistema:

Primeros pasos

Añade la siguiente configuración a tu cliente MCP:

{
  "mcpServers": {
    "yt-dlp": {
      "command": "npx",
      "args": ["-y", "@kevinwatt/yt-dlp-mcp@latest"]
    }
  }
}

Configuración del Cliente MCP

claude mcp add yt-dlp npx @kevinwatt/yt-dlp-mcp@latest

{
  "mcpServers": {
    "yt-dlp": {
      "command": "npx",
      "args": ["-y", "@kevinwatt/yt-dlp-mcp@latest"]
    }
  }
}

code --add-mcp '{"name":"yt-dlp","command":"npx","args":["-y","@kevinwatt/yt-dlp-mcp@latest"]}'

Instalación manual

npm install -g @kevinwatt/yt-dlp-mcp

🛠️ Herramientas disponibles

Todas las herramientas tienen el prefijo ytdlp_ para evitar conflictos de nombres con otros servidores MCP.

🔍 Búsqueda y Descubrimiento

📝 Subtítulos y Transcripciones

🎥 Descargas de Video y Audio

📊 Metadatos

💬 Comentarios

💡 Ejemplos de uso

Buscar videos

"Search for Python programming tutorials"
"Find the top 20 machine learning videos"
"Search for 'react hooks tutorial' and show results 10-20"
"Search for JavaScript courses in JSON format"

Obtener metadatos

"Get metadata for https://youtube.com/watch?v=..."
"Show me the title, channel, and view count for this video"
"Extract just the duration and upload date"
"Give me a quick summary of this video's info"

Obtener comentarios

"Get the top 20 comments for https://youtube.com/watch?v=..."
"Get comments as threaded JSON for this video"
"Extract comments as markdown_tree so the reply branches stay intact"
"Get newest comments with maxDepth 1 and maxRepliesPerThread 0"
"Summarize comments in threaded view"

Descargar subtítulos y transcripciones

"List available subtitles for https://youtube.com/watch?v=..."
"Download English subtitles from this video"
"Get a clean transcript of this video in Spanish"
"Download Chinese (zh-Hant) transcript"

Descargar contenido

"Download this video in 1080p: https://youtube.com/watch?v=..."
"Download audio from this YouTube video"
"Download this video from 1:30 to 2:45"
"Save this Facebook video to my Downloads"

📖 Documentación

• Referencia de API - Documentación detallada de herramientas
• Configuración - Variables de entorno y ajustes
• Configuración de cookies - Autenticación y acceso a videos privados
• Manejo de errores - Errores comunes y soluciones
• Contribuciones - Cómo contribuir

🔧 Configuración

Variables de entorno

# Downloads directory (default: ~/Downloads)
YTDLP_DOWNLOADS_DIR=/path/to/downloads

# Default resolution (default: 720p)
YTDLP_DEFAULT_RESOLUTION=1080p

# Default subtitle language (default: en)
YTDLP_DEFAULT_SUBTITLE_LANG=en

Consulta la Guía de configuración para ver la lista completa.

Proxy y archivo de configuración de yt-dlp

Todas las herramientas leen tu archivo de configuración de yt-dlp (~/.config/yt-dlp/config), por lo que cualquier opción de --proxy, --cookies u otras configuradas allí se aplican automáticamente. Este es el único canal disponible para clientes MCP que no pueden pasar variables de entorno al proceso del servidor.

Estas son alternativas: configura solo la que necesites:

Esquemas de proxy compatibles: http, https, socks4, socks5, socks5h.

YTDLP_IGNORE_CONFIG=1 no es una reversión directa a 0.9.x. Las herramientas de búsqueda, metadatos y comentarios siempre leen el archivo de configuración, por lo que este ajuste evita que también lo hagan.

Configuración de MCP con un proxy:

{
  "mcpServers": {
    "yt-dlp": {
      "command": "npx",
      "args": ["-y", "@kevinwatt/yt-dlp-mcp@latest"],
      "env": {
        "YTDLP_PROXY": "socks5://127.0.0.1:1080"
      }
    }
  }
}

Si tu cliente MCP no puede pasar variables de entorno al servidor, coloca las opciones en ~/.config/yt-dlp/config en su lugar: cada herramienta lee ese archivo:

--proxy socks5://127.0.0.1:1080
--cookies /path/to/cookies.txt

Nota: Tu archivo de configuración también se aplica a las descargas. Las opciones que cambian el formato de salida (-x, --remux-video, --recode-video) cambian lo que producen las herramientas de descarga; las herramientas informan el archivo que yt-dlp realmente escribió, por lo que el nombre informado sigue siendo correcto. Las opciones de ubicación de salida (-o, -P) no tienen efecto, porque las herramientas siempre pasan un --output absoluto en la línea de comandos, lo cual tiene prioridad.

Nota: Los archivos de configuración de yt-dlp pueden contener opciones que ejecutan comandos (--exec, --postprocessor-args, --ffmpeg-location). Estas ahora también se ejecutan en invocaciones de herramientas, incluidas las activadas por un asistente de IA. Establece YTDLP_IGNORE_CONFIG=1 si prefieres que el servidor ignore tu archivo de configuración por completo.

Configuración de Cookies

Para acceder a videos privados, contenido restringido por edad o evitar límites de velocidad, configura cookies:

⚠️ Importante: La autenticación con cookies requiere un entorno de ejecución de JavaScript (deno) instalado. Al usar cookies, YouTube utiliza endpoints de API autenticados que requieren resolver desafíos de JavaScript. Sin deno, las descargas fallarán con el error "n challenge solving failed".

Instala deno: https://docs.deno.com/runtime/getting_started/installation/

# Extract cookies from browser (recommended)
YTDLP_COOKIES_FROM_BROWSER=chrome

# Or use a cookie file
YTDLP_COOKIES_FILE=/path/to/cookies.txt

Configuración de MCP con cookies:

{
  "mcpServers": {
    "yt-dlp": {
      "command": "npx",
      "args": ["-y", "@kevinwatt/yt-dlp-mcp@latest"],
      "env": {
        "YTDLP_COOKIES_FROM_BROWSER": "chrome"
      }
    }
  }
}

Navegadores compatibles: brave, chrome, chromium, edge, firefox, opera, safari, vivaldi, whale

Consulta la Guía de configuración de cookies para obtener instrucciones detalladas.

🏗️ Arquitectura

Construido con

• yt-dlp - Motor de extracción de videos
• MCP SDK - Protocolo de Contexto de Modelo
• Zod - Validación de esquemas centrada en TypeScript
• TypeScript - Seguridad de tipos y experiencia de desarrollo

Características clave

• ✅ Seguridad de tipos: TypeScript completo con modo estricto
• ✅ Entradas validadas: Esquemas Zod para validación en tiempo de ejecución
• ✅ Límites de caracteres: Truncamiento automático para evitar desbordamiento de contexto
• ✅ Anotaciones de herramientas: Sugerencias de solo lectura, destructivas e idempotentes
• ✅ Orientación de errores: Mensajes de error accionables para LLMs
• ✅ Diseño modular: Separación clara de responsabilidades

📊 Formatos de respuesta

Formato JSON

Perfecto para procesamiento programático:

{
  "total": 50,
  "count": 10,
  "offset": 0,
  "videos": [...],
  "has_more": true,
  "next_offset": 10
}

Formato Markdown

Visualización legible para humanos:

Found 50 videos (showing 10):

1. **Video Title**
   📺 Channel: Creator Name
   ⏱️  Duration: 10:30
   🔗 URL: https://...

Árbol de comentarios en Markdown

Útil para análisis de LLM cuando el contexto de respuesta importa:

# AI-Ready Comment Threads

source_title: "Sample Video"
comments_detected: 20
root_threads: 6
reply_comments: 14

## Threads

### Thread 1

- comment_id: "abc123"
  parent_id: "root"
  depth: 0
  reply_count: 2
  text:
    | Root comment text
  - comment_id: "reply456"
    parent_id: "abc123"
    depth: 1
    reply_count: 0
    text:
      | Reply text

Límites de comentarios

La extracción de comentarios de YouTube admite la tupla completa del extractor:

youtube:comment_sort=<sort>;max_comments=<total>,<parents>,<replies>,<repliesPerThread>,<depth>

Ejemplos:

• Comportamiento predeterminado: maxComments=20 produce max_comments=20,20,20,20,2
• Solo comentarios raíz: maxDepth=1, maxRepliesPerThread=0
• Ramificación limitada: maxReplies=40, maxRepliesPerThread=5, maxDepth=2

🔒 Privacidad y seguridad

• Sin seguimiento: Descargas directas, sin análisis
• Validación de entradas: Los esquemas Zod previenen inyecciones
• Validación de URL: Verificación estricta del formato de URL
• Límites de caracteres: Previene ataques de desbordamiento de contexto
• Solo lectura por defecto: La mayoría de las herramientas no modifican el estado del sistema

🤝 Contribuciones

¡Las contribuciones son bienvenidas! Consulta nuestra Guía de contribuciones.

1. Haz un fork del repositorio
2. Crea una rama de características (git checkout -b feature/amazing-feature)
3. Realiza tus cambios (git commit -m 'Add amazing feature')
4. Haz push a la rama (git push origin feature/amazing-feature)
5. Abre una Solicitud de Extracción

📝 Licencia

Este proyecto está licenciado bajo la Licencia MIT: consulta el archivo LICENCIA para más detalles.

🙏 Agradecimientos

• yt-dlp - La increíble herramienta de extracción de videos
• Anthropic - Por el Protocolo de Contexto de Modelo
• Dive - Plataforma de IA compatible con MCP

📚 Proyectos relacionados

• Servidores MCP - Implementaciones oficiales de servidores MCP
• yt-dlp - Descargador de videos por línea de comandos
• Dive Desktop - Plataforma de agentes de IA