youtube-transcript-mcp

Un servidor MCP que permite a un agente de programación leer y buscar transcripciones de vídeos de YouTube. Sin clave de API, sin cuenta de Google, sin necesidad de registrarse. Extrae los subtítulos a través de los endpoints públicos de YouTube y añade una pequeña cosa que un volcado de transcripción en bruto no te da: resúmenes de capítulos.

Esto empezó como una pequeña herramienta para mi propio uso. Me seguía encontrando con conversaciones que contenían un enlace de YouTube y necesitaba saber qué decía realmente el vídeo, y volver a pegar transcripciones era una pérdida de tiempo. Se convirtió en un servidor reutilizable para que cualquier cosa que se ejecute con el Model Context Protocol pudiera simplemente preguntar.

Qué hace

Cuatro herramientas.

• get_transcript(video_url_or_id, languages=["en"], include_timestamps=False) obtiene la transcripción completa como texto plano. Acepta una URL completa de YouTube (watch?v=, youtu.be, /embed/, /shorts/, /live/) o un ID de vídeo de 11 caracteres.

• get_video_metadata(video_url_or_id) devuelve el título, el nombre del canal, la URL del canal y la miniatura a través del endpoint oEmbed sin autenticación de YouTube. Deliberadamente no devuelve la fecha de publicación ni la descripción completa, porque esas necesitan una clave oficial de la API de Datos y el objetivo aquí es que no la necesitas.

• search_transcript(video_url_or_id, query, languages=["en"]) encuentra los segmentos que coinciden con una palabra clave o frase, sin distinguir mayúsculas de minúsculas, cada uno con una marca de tiempo [mm:ss] para que el modelo pueda señalar dónde en el vídeo se dijo algo.

• summarize_chapters(video_url_or_id, gap_seconds=4.0, min_chunk_seconds=45.0, languages=["en"]) divide la transcripción en bloques de tiempo aproximados en pausas naturales y los devuelve para que un agente pueda resumir sección por sección en lugar de tragarse un bloque gigante. Es una heurística, no los datos reales de capítulos de YouTube.

Todas las herramientas devuelven una cadena de texto simple, incluidos los errores (por ejemplo, "Error: captions are disabled for this video"). No se exponen excepciones al agente que llama, y no se filtran trazas de pila.

Related MCP server: youtube-mcp

Qué no hace deliberadamente

• No funciona con vídeos con subtítulos desactivados, vídeos privados o no disponibles, ni transmisiones en directo sin subtítulos. Lo dice en lugar de adivinar.

• No depende de la API de Datos de YouTube. No puedes obtener fechas de publicación ni descripciones completas sin una, por diseño.

• No almacena en caché. Dos llamadas al mismo vídeo vuelven a obtener los datos ambas veces. Está bien para el uso real de la herramienta. Añade caché si alguna vez lo necesitas a gran escala.

Configuración

Requiere Python 3.11+ y uv.

uv sync

Ejecútalo de forma independiente para confirmar que arranca:

uv run server.py

Se queda esperando la entrada de MCP stdio, así que parecerá que no hace nada hasta que un cliente se conecte. Eso es normal. Ctrl+C para salir.

Registro con un cliente MCP

Añádelo a la configuración MCP de tu cliente. El servidor se invoca con stdio, así que la configuración es una línea de comandos. Usando Claude CLI como ejemplo:

claude mcp add youtube-transcript -- uv --directory /absolute/path/to/youtube-transcript-mcp run server.py

O en la configuración JSON:

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/youtube-transcript-mcp", "run", "server.py"]
    }
  }
}

Notas aprendidas por las malas

• Solo funcionan los vídeos con subtítulos (autogenerados o manuales). Un vídeo sin subtítulos devuelve un error claro, que es una elección deliberada: un resultado vacío parece un fallo silencioso, un error lo nombra.

• La lista de idiomas importa. languages=["en"] obtiene la pista en inglés cuando existe. Si un canal sube solo en otro idioma, pasa ese código.

• Fija mcp>=1.28.1 pero mantente por debajo de 2.0. mcp 2.x renombró mcp.server.fastmcp y la importación falla silenciosamente al arrancar el servidor. Quieres la versión que realmente carga.

Licencia

MIT. Ver LICENSE.