🎬 claude-youtube-transcript

Pega una URL de YouTube en Claude Desktop y obtén la transcripción completa del video.

Un servidor MCP mínimo que le da a Claude una herramienta —get_transcript— para leer los subtítulos de cualquier video de YouTube que los tenga. Sin API keys, sin cuenta de Google, sin descargar el video: solo la pista de texto, en un bloque continuo listo para que el modelo lo resuma, lo traduzca o lo cite.

---

✨ Qué hace

• Acepta cualquier formato de URL — watch?v=, youtu.be/, /shorts/, /embed/, /live/, o el ID pelado de 11 caracteres.
• Prioriza español, cae a inglés y, si no hay pista humana, usa los subtítulos generados automáticamente.
• Compatible con youtube-transcript-api 0.6 y 1.x — prueba la API clásica, la de instancia y el listado de pistas, en ese orden.
• Devuelve texto plano continuo, sin timestamps ni marcas de [Música], para no gastar contexto de más.

📋 Requisitos

• Claude Desktop (macOS, Windows o Linux).
• Python 3.10 o superior en el PATH.
• Nada más: sin API keys, sin cuenta de Google, sin ffmpeg.

🚀 Instalación rápida

macOS / Linux

git clone https://github.com/Magiprr/claude-youtube-transcript.git && cd claude-youtube-transcript && ./install.sh

<a name="windows"></a>

Windows

En PowerShell:

git clone https://github.com/Magiprr/claude-youtube-transcript.git; cd claude-youtube-transcript; powershell -ExecutionPolicy Bypass -File .\install.ps1

El -ExecutionPolicy Bypass es necesario porque Windows bloquea por defecto los scripts sin firmar. Aplica solo a esa ejecución, no cambia la política del sistema.

El instalador (en ambos sistemas):

1. 📦 Instala las dependencias con pip --break-system-packages.
2. 🔍 Detecta la ruta absoluta de server.py y del binario de python3.
3. 💾 Respalda tu claude_desktop_config.json antes de tocarlo.
4. 🤝 Fusiona el bloque youtube-transcript sin pisar los servidores MCP que ya tengas.
5. 🔄 Te indica que reinicies Claude Desktop (Cmd + Q, no solo cerrar la ventana).

Instalación manual

Si prefieres hacerlo a mano, agrega esto a ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "/opt/homebrew/bin/python3",
      "args": ["/ruta/absoluta/a/claude-youtube-transcript/server.py"]
    }
  }
}

Ambas rutas tienen que ser absolutas. La de Python la obtienes con which python3 (o where python en Windows).

La ubicación del archivo depende del sistema:

Sistema	Ruta
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

En Windows, las rutas dentro del JSON llevan doble barra invertida (C:\\Users\\tu-usuario\\...) o barra normal. El instalador lo escribe bien solo.

🔎 Qué recibe Claude

La herramienta devuelve un bloque plano, sin timestamps ni marcas de sonido:

Transcripcion de https://www.youtube.com/watch?v=VIDEO_ID

Hoy vamos a ver como funciona el protocolo MCP y por que cambia la forma
en que las aplicaciones le dan herramientas a un modelo de lenguaje...

Así el modelo gasta el contexto en el contenido y no en metadatos.

💬 Ejemplos de prompts

Una vez reiniciado Claude Desktop:

Resúmeme este video en 10 bullets: https://www.youtube.com/watch?v=dQw4w9WgXcQ

Extrae de este video todas las cifras que menciona, con el contexto de cada una:
https://youtu.be/dQw4w9WgXcQ

Traduce al español la transcripción de https://www.youtube.com/shorts/dQw4w9WgXcQ

Compara qué dicen estos dos videos sobre el mismo tema:
<url 1>
<url 2>

De este video, dame solo las partes donde habla de precios, citadas textual:
<url>

🩺 Solución de problemas

<details> <summary><strong>La herramienta no aparece en Claude Desktop</strong></summary>

Cierra la app por completo y vuelve a abrirla. En macOS es Cmd + Q; en Windows no basta con la X, hay que hacer click derecho en el icono de la bandeja del sistema y elegir Quit. En ambos casos, cerrar la ventana no mata el proceso. Después verifica que el bloque haya quedado bien escrito:

python3 -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json

</details>

<details> <summary><strong><code>error: externally-managed-environment</code> al instalar</strong></summary>

Es el Python de Homebrew protegiéndose. El instalador ya usa --break-system-packages; si lo ejecutas a mano:

python3 -m pip install -r requirements.txt --break-system-packages

Si prefieres no tocar el Python del sistema, usa un venv y apunta el command del config a /ruta/al/venv/bin/python. </details>

<details> <summary><strong><code>ModuleNotFoundError: No module named 'mcp'</code> en los logs</strong></summary>

Claude Desktop está usando un Python distinto al que instaló las dependencias. Comprueba cuál quedó en el config y que ese mismo tenga el paquete:

/opt/homebrew/bin/python3 -c "import mcp, youtube_transcript_api; print('ok')"

</details>

<details> <summary><strong>"No hay transcripción disponible"</strong></summary>

No todos los videos tienen subtítulos: el autor puede haberlos desactivado, o el video puede ser privado, con restricción de edad o una transmisión en vivo en curso. Verifica en YouTube que el botón CC exista. </details>

<details> <summary><strong><code>Too Many Requests</code> / la IP quedó bloqueada</strong></summary>

YouTube limita las consultas por IP. Suele pasar en redes compartidas o VPN. Espera unos minutos, o prueba desde otra conexión. </details>

<details> <summary><strong><code>no se puede cargar el archivo install.ps1</code> (Windows)</strong></summary>

Es la política de ejecución de PowerShell. Ejecútalo así:

powershell -ExecutionPolicy Bypass -File .\install.ps1

Si además Windows marcó el archivo como descargado de internet:

Unblock-File .\install.ps1

</details>

<details> <summary><strong>Windows abre la Microsoft Store al escribir <code>python</code></strong></summary>

Es el alias stub que trae Windows. Instala Python real desde python.org marcando "Add python.exe to PATH". El instalador ya ignora ese stub al buscar el intérprete. </details>

<details> <summary><strong>Ver los logs del servidor MCP</strong></summary>

# macOS
tail -f ~/Library/Logs/Claude/mcp-server-youtube-transcript.log

# Windows
Get-Content -Wait "$env:APPDATA\Claude\Logs\mcp-server-youtube-transcript.log"

</details>

🛠️ Desarrollo

Puedes ejecutar el servidor a mano para comprobar que levanta:

python3 server.py

Queda esperando por stdio (así lo habla Claude Desktop): que no imprima nada es señal de que está bien.

📄 Licencia

MIT © 2026

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.