YouTube Knowledge MCP

Un servidor de Model Context Protocol (MCP) que ofrece a los asistentes de IA la capacidad de buscar, analizar y extraer conocimiento de los vídeos de YouTube. Funciona con Claude Desktop, Claude Code, Claude.ai, Cursor y cualquier cliente compatible con MCP.

Admite tanto transporte local (stdio) como remoto (Streamable HTTP).

Características

Buscar y leer

• Buscar vídeos y canales por palabra clave

• Obtener vídeos de una lista de reproducción o canal

• Metadatos de vídeo, canal y lista de reproducción, capítulos y comentarios principales

• Transcripciones con marcas de tiempo, segmentadas por rango de tiempo o capítulo, y limitadas para que un vídeo de tres horas no inunde tu contexto

• Buscar dentro de una transcripción y obtener enlaces ?t= que abren el vídeo en el momento exacto

• Herramientas por lotes: transcripciones de muchos vídeos a la vez, o un resumen de una lista de reproducción completa

Extraer para edición

• Recortar un rango de tiempo sin descargar el vídeo completo, cortar con precisión o en fotogramas clave, por marca de tiempo o nombre de capítulo

• Clips de audio en mp3, m4a, wav, flac u opus

• Captura de fotogramas en cualquier marca de tiempo, sin descargar el archivo

• Exportación de subtítulos como SRT, WebVTT o texto plano para Premiere, Resolve o CapCut

• Descargas completas con ajustes predefinidos de calidad

Conserva lo que aprendas (modo local)

• Guarda resúmenes y notas de habilidades en una biblioteca local

• Léelos de nuevo y busca entre todos con clasificación de texto completo

• Etiqueta, vuelve a etiquetar y elimina

Construye un cerebro para un canal (modo local)

• Lee un canal completo y conviértelo en un corpus de pasajes con marcas de tiempo, en cualquier idioma de subtítulos, reanudable y seguro de interrumpir: una segunda ejecución continúa donde se detuvo y recoge nuevas subidas

• Pregunta qué ha dicho un creador sobre cualquier cosa, en todos los vídeos, y obtén los propios momentos con enlaces que abren el vídeo en ese punto

• Mide el canal: cuánto era legible, su ritmo de publicación, su velocidad de habla y las frases que repite en los vídeos

• Mantén un perfil escrito junto al corpus, basado en pasajes que puedas citar

Diseñado para seguir funcionando

• WebVTT analizado por la implementación de referencia del W3C, no por un comparador escrito a mano

• Errores tipados y accionables — «sin subtítulos en en, prueba: fr, es, de» en lugar de un muro de stderr de yt-dlp

• Tiempos de espera, reintentos con retroceso y un límite de concurrencia en cada llamada a yt-dlp

• check_health diagnostica yt-dlp y ffmpeg faltantes o desactualizados

• Salida estructurada en cada herramienta, además de recursos, prompts y completions de MCP

Related MCP server: YouTube Translate MCP

Requisitos previos

• Node.js 22+

• yt-dlp — necesario para todas las herramientas. brew install yt-dlp (macOS) o pip install -U yt-dlp

• ffmpeg — necesario para descargas, extracción de clips y captura de fotogramas. Todo lo demás funciona sin él.

Ejecuta la herramienta check_health para confirmar que ambos están instalados y actualizados. Un yt-dlp desactualizado es la causa más común de fallos inexplicables, ya que YouTube cambia con frecuencia; yt-dlp -U soluciona la mayoría de ellos.

Instalación

Mediante npm (recomendado)

npm install -g youtube-knowledge-mcp

Mediante npx (sin instalación)

Configúralo directamente con npx (consulta la sección de Configuración).

Desde el código fuente

git clone https://github.com/teobouancheau/youtube-knowledge-mcp.git
cd youtube-knowledge-mcp
npm install
npm run build

Configuración

Local (stdio) — Claude Desktop, Claude Code, Cursor

Inicio rápido con npx

{
  "mcpServers": {
    "youtube-knowledge": {
      "command": "npx",
      "args": ["-y", "youtube-knowledge-mcp"]
    }
  }
}

Con instalación global

npm install -g youtube-knowledge-mcp

{
  "mcpServers": {
    "youtube-knowledge": {
      "command": "youtube-knowledge-mcp"
    }
  }
}

Ubicaciones de los archivos de configuración

Reinicia tu cliente después de actualizar la configuración.

Remoto (HTTP) — Claude.ai, Claude Mobile, conectores personalizados

El servidor admite transporte Streamable HTTP para acceso remoto mediante los conectores oficiales de Claude.

Cada configuración remota es tu propio despliegue. No hay ninguna instancia compartida a la que apuntar un conector, por diseño: cada llamada invoca a yt-dlp, por lo que un único host que sirva tráfico de otras personas es un host al que YouTube limita la velocidad para todos. El botón de abajo despliega este repositorio en tu propia cuenta de Render, en unos dos minutos y sin clonar nada.

Autohospedado

npm run build
npm run start:http

El servidor escucha en PORT (por defecto 3000). Cambia la variable de entorno PORT para modificarlo.

Docker

docker build -t youtube-knowledge-mcp .

TOKEN=$(openssl rand -hex 32) && echo "MCP_AUTH_TOKEN=$TOKEN"
docker run -p 3000:10000 -e MCP_AUTH_TOKEN="$TOKEN" youtube-knowledge-mcp

El token se imprime porque nada más lo imprimirá: el servidor registra que se requiere un token, pero nunca su valor. Envíalo como Authorization: Bearer $TOKEN.

La imagen establece PORT=10000 y lo expone; publícalo en el puerto del host que quieras. La compilación se realiza dentro de la imagen, así que no hace falta un npm run build local previo.

Desplegar en Render

El botón abre el flujo Blueprint de Render con render.yaml de este repositorio, que compila la imagen de Docker, apunta la comprobación de salud a /health y genera un MCP_AUTH_TOKEN para ti. Sin fork, sin clon, sin ajustes que rellenar: el servicio es tuyo, en tu cuenta.

1. Haz clic en el botón y confirma. Render compila la imagen y la despliega.

2. Abre la pestaña Entorno del servicio y copia el MCP_AUTH_TOKEN generado. El transporte HTTP rechaza cualquier solicitud sin él, así que una URL que se filtre no es un servidor abierto.

3. Añade https://<your-service>.onrender.com/mcp como conector personalizado, con Authorization: Bearer <token>.

Vale la pena hacer esto una vez que el servicio exista: establece MCP_ALLOWED_HOSTS al nombre de host de tu servicio (<your-service>.onrender.com). No puede rellenarse desde el Blueprint, ya que el nombre de host no existe hasta que existe el servicio, y rechaza las solicitudes que lleguen bajo cualquier otro nombre.

Tu instancia no sigue este repositorio. El Blueprint establece autoDeployTrigger: off, porque el despliegue automático ejecutaría código subido aquí dentro de tu cuenta, bajo tu token, sin que lo leas antes. Para usar una versión más reciente, utiliza Despliegue manual en el servicio.

El plan gratuito se duerme tras la inactividad, así que la primera llamada después de una pausa espera a un arranque en frío. Cualquier plan de pago elimina eso.

Conectar mediante Claude.ai

1. Ve a Configuración > Conectores

2. Haz clic en Añadir conector personalizado

3. Introduce la URL de tu servidor (p. ej., https://your-app.onrender.com/mcp)

4. Añade la cabecera Authorization: Bearer <token> si configuraste MCP_AUTH_TOKEN

5. Haz clic en Añadir

Herramientas MCP

33 herramientas. Las 14 de solo lectura funcionan en ambos transportes; las 19 que tocan tu sistema de archivos se registran solo en modo local (stdio), por lo que un despliegue remoto no puede acceder al disco del host.

Cada herramienta devuelve texto legible por humanos y salida estructurada tipada, y reporta los fallos como un mensaje accionable — [NO_CAPTIONS] No "en" captions are available for this video. Call get_transcript again with one of: fr, es, de.

Descubrimiento — remoto + local

Biblioteca de conocimientos — solo local

Cerebros de canal — solo local

build_brain es el único que toca la red. El resto resuelve un canal a partir de lo que ya hay en disco, por lo que funcionan sin conexión y no cuestan nada llamarlos.

Un cerebro contiene un único idioma de subtítulos; pasa language para leer otro y crea un cerebro separado por idioma.

since y minDurationSeconds describen el cerebro, no solo la llamada que los pasó. Se vuelven a aplicar cada vez, así que estrechar uno elimina los pasajes de los vídeos que excluye, y ampliarlo los vuelve a leer — por eso build_brain está anotado como destructivo. Si un vídeo cumple los requisitos se decide a partir de la fecha y la duración ya registradas, así que cambiar de opinión no cuesta ninguna petición hasta que haya algo nuevo que obtener. Esos valores provienen de los metadatos de cada vídeo, nunca de una suposición: una lista plana de canal no incluye fecha de publicación en absoluto.

build_brain también repara. Si el archivo de pasajes se pierde o se trunca, los vídeos que ya no puede justificar se vuelven a leer en la siguiente llamada en lugar de omitirse para siempre como ya hechos.

Prompts

Flujos de trabajo reutilizables que tu cliente puede invocar directamente: summarize_video, extract_skill, compare_videos, research_topic, channel_deep_dive, clip_from_quote (encontrar una frase y luego cortar el clip alrededor de ella), y — solo local — review_library, create_brain (crear el corpus de un canal y luego escribir su perfil a partir de él) y ask_creator (responder una pregunta estrictamente desde un cerebro, con citas).

Recursos

• youtube://transcript/{videoId} — una transcripción con marcas de tiempo, obtenida y almacenada en caché en la primera lectura

• youtube://library/{videoId}/{summary|skill} — una nota guardada (solo local y enumerable)

• youtube://brain/{channelId}/{manifest|profile} — lo que cubre el cerebro de un canal, o el perfil escrito a partir de él (solo local y enumerable)

Códigos de error

Los fallos se notifican dentro del resultado para que el modelo pueda leerlos y recuperarse de ellos, cada uno con un prefijo de código y seguido de un siguiente paso.

Variables de entorno

Todas opcionales.

Almacenamiento de la biblioteca

El contenido se almacena en ~/.youtube-knowledge/:

~/.youtube-knowledge/
├── transcripts/          # Cached timestamped transcripts
│   └── {video_id}.{lang}.json
├── library/              # Saved notes
│   └── {video_id}/
│       ├── metadata.json
│       ├── summary.md
│       └── skill.md
├── brains/               # Channel brains
│   └── {channel_id}/
│       ├── manifest.json # What the brain covers, and where a build stopped
│       ├── chunks.json   # The timestamped passages
│       └── profile.md    # The written account, if one was saved
├── downloads/            # Full downloads
├── clips/                # Extracted clips
├── frames/               # Captured stills
├── subtitles/            # Exported SRT / VTT / TXT
├── index.json            # Library index
└── search-index.json     # Full-text search index

Las transcripciones se almacenan en caché durante 30 días por defecto; pasa refresh: true a cualquier herramienta de transcripción para omitir la caché, o establece YOUTUBE_MCP_TRANSCRIPT_TTL_MS.

Toda herramienta que escribe archivos limita su salida a tu directorio personal, y outputDir es rechazado si apunta a cualquier otro lugar.

Ejemplos de uso

Encontrar un momento y citarlo

"Find where this video talks about rate limiting and give me the timestamp:
 https://youtube.com/watch?v=..."

search_transcript devuelve cada coincidencia con un enlace que abre el vídeo en ese segundo, de modo que la afirmación se puede comprobar en lugar de aceptarse sin más.

Encontrar un momento y recortarlo

"Find where she says 'the real bottleneck was the database' and cut me a
 30-second clip around it"

search_transcript localiza el momento, extract_clip lo corta. Solo se descarga el rango de bytes que cubre el clip.

Leer una sección de un vídeo largo

"Summarize just the 'Benchmarks' chapter of this 3-hour podcast"

get_chapters encuentra la sección, y luego get_transcript con chapter: "Benchmarks" lee solo esa parte en lugar de todo el vídeo.

Examinar una lista de reproducción de forma económica

"What does this 40-video course cover, and which three videos should I watch?"

digest_playlist devuelve los metadatos y capítulos de cada vídeo en una sola llamada.

Preparar material para una edición

"Pull these four moments as separate clips and export the subtitles as SRT"

extract_clips corta los cuatro en una sola llamada; export_subtitles escribe un archivo que tu editor puede importar.

Crear y consultar una base de conocimiento

"Summarize this video and save it to my library tagged 'databases'"
"What have I saved about connection pooling?"

save_to_library la guarda; search_library busca en todo lo guardado con clasificación de texto completo.

Crear un cerebro para un creador

"Build a brain for @Fireship, then tell me everything they've said about Rust"

build_brain lee el canal en pasajes con marcas de tiempo: interrúmpelo y vuelve a llamarlo para continuar. Luego ask_brain responde a partir de lo que realmente se dijo, devolviendo los propios momentos para que cada afirmación se pueda comprobar con el vídeo. Vuelve a ejecutar build_brain un mes después y leerá solo las nuevas subidas.

Pruebas

npm test              # Run all tests
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report, with thresholds enforced

La suite cubre la lógica pura directamente, maneja el servidor real a través de un cliente MCP sobre un transporte en memoria, ejercita la biblioteca contra un sistema de archivos temporal real y captura el manifiesto de herramientas para que cualquier cambio en la superficie pública aparezca como una diferencia revisable.

Desarrollo

npm run dev        # Watch mode
npm run build      # Build for production
npm run rebuild    # Clean and rebuild
npm start          # Run server (stdio)
npm run start:http # Run server (HTTP)
npm run validate   # Typecheck + lint + format check + test

La CI ejecuta la misma comprobación en Node 22 y 24 para cada push y pull request, y luego arranca el servidor compilado como un cliente MCP real para verificar el manifiesto.

Contribuir

Las contribuciones son bienvenidas: consulta CONTRIBUTING.md para conocer la estructura del proyecto, los estándares de codificación y cómo añadir una herramienta.

Seguridad

El transporte HTTP no está autenticado a menos que establezcas MCP_AUTH_TOKEN. Consulta SECURITY.md antes de exponerlo más allá de localhost y para informar de una vulnerabilidad.

Licencia

Licencia MIT: consulta LICENSE para más detalles.

Agradecimientos

• yt-dlp para la extracción de YouTube

• Anthropic para el Protocolo de Contexto del Modelo