claude-youtube-transcript
by Magiprr
README.md
# 🎬 claude-youtube-transcript
[](https://www.python.org/)
[](https://modelcontextprotocol.io/)
[](#-licencia)
[](#-instalación-rápida)
[](#windows)
**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
```bash
git clone https://github.com/Magiprr/claude-youtube-transcript.git && cd claude-youtube-transcript && ./install.sh
```
<a name="windows"></a>
### Windows
En PowerShell:
```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`:
```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:
```text
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:
```bash
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:
```bash
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:
```bash
/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
powershell -ExecutionPolicy Bypass -File .\install.ps1
```
Si además Windows marcó el archivo como descargado de internet:
```powershell
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](https://www.python.org/downloads/) 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>
```bash
# macOS
tail -f ~/Library/Logs/Claude/mcp-server-youtube-transcript.log
```
```powershell
# 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:
```bash
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.
```
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo issues