# YouTube MCP
Una implementación de Model Context Protocol (MCP) para buscar y reproducir canciones en YouTube directamente desde tu navegador.
## Tabla de Contenidos
- [Características](#características)
- [Instalación](#instalación)
- [Uso](#uso)
- [Tests](#tests)
- [Calidad de Código](#calidad-de-código)
- [Estructura del Proyecto](#estructura-del-proyecto)
- [Herramientas Disponibles](#herramientas-disponibles)
- [Ejemplos de Prompts](#ejemplos-de-prompts)
- [Requisitos de API Key](#requisitos-de-api-key)
- [Soporte de Sistemas Operativos](#soporte-de-sistemas-operativos)
- [Licencia](#licencia)
- [Contribuciones](#contribuciones)
## Características
- 🔍 Buscar canciones en YouTube usando la API oficial
- 🎵 Reproducir canciones en el navegador automáticamente
- 🖥️ Soporte multi-plataforma (Windows, macOS, Linux)
- 📦 Fácil integración con herramientas que soporten MCP
- ✅ Validación completa de inputs (API Keys, URLs, búsquedas)
- 📝 Type hints modernos (Python 3.9+)
- 🧪 Cobertura de tests completa (59 tests, 100% passing)
- 📊 Logging estructurado y centralización de configuración
## Instalación
### 1. Clonar/Crear el proyecto
```bash
cd youtube_mcp
# O: git clone https://github.com/roquevaamonde/youtube-mcp.git youtube_mcp
```
### 2. Crear el virtual environment
```bash
python -m venv venv
source venv/bin/activate # En Windows: venv\Scripts\activate
```
### 3. Instalar dependencias
```bash
pip install -r requirements.txt
```
### 4. Configurar API Key
Sigue estos pasos para obtener tu API Key de YouTube:
1. **Acceder a Google Cloud Console**: Dirígete a [Google Cloud Console](https://console.cloud.google.com/)
2. **Crear un nuevo proyecto**:
- Haz clic en el selector de proyecto en la parte superior
- Selecciona "Nuevo Proyecto"
- Asigna un nombre (ej: "YouTube MCP")
- Clic en "Crear"
3. **Habilitar YouTube Data API v3**:
- Ve a [APIs & Services > Library](https://console.cloud.google.com/apis/library)
- Busca "YouTube Data API v3"
- Haz clic en el resultado
- Clic en "Habilitar"
4. **Crear una API Key**:
- Ve a [APIs & Services > Credentials](https://console.cloud.google.com/apis/credentials)
- Clic en "Crear credenciales" → "Clave de API"
- Copia la clave generada
5. **Configurar en tu proyecto**:
```bash
cp .env.example .env
# Edita .env y añade tu YOUTUBE_API_KEY
# YOUTUBE_API_KEY=tu_clave_aqui
```
### 5. Configurar en VS Code
1. Abre las configuraciones de VS Code (`Cmd+Shift+P` → "Preferences: Open User Settings (JSON)")
2. Localiza o crea la sección `"modelContextProtocol"`
3. Agrega la configuración del servidor YouTube:
```json
{
"modelContextProtocol": {
"servers": {
"youtube": {
"type": "stdio",
"command": "{python-path}",
"args": ["{project-path}/youtube_mcp_server.py"],
"disabled": false,
"autoApprove": [],
"env": {
"YOUTUBE_API_KEY": "your_api_key_here"
}
}
}
}
}
```
Reemplaza:
- `{python-path}`: Ruta completa a tu Python (ej: `/usr/bin/python3` o `C:\Python\python.exe`)
- `{project-path}`: Ruta del proyecto (ej: `/home/user/projects/youtube_mcp`)
- `your_api_key_here`: Tu API Key de YouTube
## Uso
```python
from youtube_mcp.server import YouTubeMCPServer
server = YouTubeMCPServer(api_key="your_api_key")
# Ejemplo 1: Reproducir el primer resultado (tema suelto)
results = server.handle_search_youtube(query="Bohemian Rhapsody Queen", max_results=5)
if results.get("success") and results.get("results"):
first_url = results["results"][0]["url"]
server.handle_play_youtube(first_url)
```
Snippets MCP (JSON) para el mismo flujo:
```json
{
"tool": "search_youtube",
"params": {
"query": "Bohemian Rhapsody Queen",
"max_results": 5
}
}
```
Con el `url` del primer resultado devuelto, reproducir:
```json
{
"tool": "play_youtube",
"params": {
"url": "https://www.youtube.com/watch?v=<VIDEO_ID>"
}
}
```
### Ejemplos avanzados
- Playlist con orden explícito (por IDs conocidos):
Python:
```python
video_ids = ["VIDEO1", "VIDEO2", "VIDEO3", "VIDEO4"]
# Método recomendado (determinista): watch_videos con video_ids
playlist_url = f"https://www.youtube.com/watch_videos?video_ids={','.join(video_ids)}"
server.handle_play_youtube(playlist_url)
```
JSON MCP:
```json
{
"tool": "play_youtube",
"params": {
"url": "https://www.youtube.com/watch_videos?video_ids=VIDEO1,VIDEO2,VIDEO3,VIDEO4"
}
}
```
Alternativa (menos determinista en algunos navegadores):
```json
{
"tool": "play_youtube",
"params": {
"url": "https://www.youtube.com/watch?v=VIDEO1&playlist=VIDEO2,VIDEO3,VIDEO4&autoplay=1"
}
}
```
- Reproducción continua (Mix de YouTube) para un tema:
Python:
```python
video_id = "VIDEO_ID"
mix_url = f"https://www.youtube.com/watch?v={video_id}&list=RD{video_id}&autoplay=1"
server.handle_play_youtube(mix_url)
```
JSON MCP:
```json
{
"tool": "play_youtube",
"params": {
"url": "https://www.youtube.com/watch?v=VIDEO_ID&list=RDVIDEO_ID&autoplay=1"
}
}
```
## Tests
```bash
pytest tests/
```
**Cobertura de Tests**: 59 tests que cubren:
- ✅ Búsqueda de canciones en YouTube (YouTubeClient)
- ✅ Reproducción de videos en navegador (BrowserController)
- ✅ Detección de Sistema Operativo (Windows, macOS, Linux, WSL)
- ✅ Gestión de procesos de navegador
- ✅ Validadores de URL, API Keys, búsquedas y max_results
- ✅ Servidor MCP y orquestación de herramientas
- ✅ Manejo de errores y casos edge
Para ver la cobertura de código:
```bash
pytest tests/ --cov=youtube_mcp --cov-report=term-missing
```
## Calidad de Código
Este proyecto incluye:
- **Validación de inputs**: Módulo `validators.py` con validación completa para:
- API Keys (longitud mínima 20 caracteres)
- URLs de YouTube (validación con regex)
- Queries de búsqueda (1-300 caracteres)
- Max results (1-50)
- **Type hints modernos**: Uso de `dict`, `list`, `tuple` en lugar de `typing` (Python 3.9+)
- **Logging estructurado**: Setup centralizado con `logger.py`
- **Constantes**: Configuración centralizada en `constants.py` para:
- Mensajes de error y éxito
- Detectores de SO (Windows, macOS, Linux, WSL)
- Configuración por defecto (región, max_results)
- Formato de logging
## Estructura del proyecto
```
youtube_mcp/
├── youtube_mcp/
│ ├── __init__.py
│ ├── youtube_client.py # Cliente de YouTube API
│ ├── browser_controller.py # Controlador de navegador multi-plataforma
│ ├── server.py # Servidor MCP con herramientas
│ ├── validators.py # Validación de inputs
│ ├── constants.py # Constantes y configuración centralizada
│ └── logger.py # Setup de logging
├── tests/ # Tests con pytest (59 tests, 100% passing)
├── config/ # Archivos de configuración
├── docs/ # Documentación
├── requirements.txt
├── .env.example
└── README.md
```
## Herramientas disponibles
### search_youtube
Busca una canción en YouTube.
**Parámetros:**
- `query` (string, requerido): Nombre de la canción o artista
- `max_results` (integer, opcional): Número máximo de resultados (default: 5)
- `play` (boolean, opcional): Si es true, abre el primer resultado en el navegador
**Ejemplo:**
```json
{
"query": "Bohemian Rhapsody Queen",
"max_results": 5,
"play": false
}
```
### play_youtube
Reproduce una canción en YouTube abriendo el enlace del video en el navegador.
**Parámetros:**
- `url` (string, requerido): Enlace de YouTube del video a reproducir
**Ejemplo:**
```json
{
"url": "https://www.youtube.com/watch?v=<VIDEO_ID>"
}
```
También puedes pasar URLs de playlist o Mix:
```json
{
"url": "https://www.youtube.com/watch?v=VIDEO1&playlist=VIDEO2,VIDEO3,VIDEO4&autoplay=1"
}
```
```json
{
"url": "https://www.youtube.com/watch?v=VIDEO_ID&list=RDVIDEO_ID&autoplay=1"
}
```
## Ejemplos de Prompts
A continuación tienes ejemplos prácticos para pedir búsquedas, listas/colas y reproducción en bucle o continua. Puedes combinarlos y ser específico con el orden, el artista y la cantidad.
- Reproducción directa (tema suelto):
- "Pon King Kong de Midas Alonso"
- "Reproduce Bohemian Rhapsody de Queen y súbelo a 1080p si hay opción"
- Reproducción en bucle o continua:
- "Déjalo en bucle" (el agente puede activar el modo loop del reproductor o usar el Mix de YouTube cuando corresponda)
- "Activa el Mix de YouTube de esta canción para que siga solo"
- "Ponlo en repetición por 30 minutos"
- Listas/colas personalizadas (orden explícito):
- "Prepárame una cola con BRIXTON, GRAND PRIX, CLUEDO y TYRION de Midas Alonso en ese orden y reprodúcela"
- "Crea una playlist de 8 temas de Yung Beef empezando por Me Perdí en Madrid y mezclando con artistas similares"
- Búsquedas versátiles y por criterios:
- "Busca 5 temas de PXXR GVNG y pon el mejor resultado oficial"
- "Haz una playlist de 10 temas de rap español 2015–2018 y reprodúcela"
- "Mezcla clásicos de Yung Beef con temas nuevos y activa autoplay"
Notas:
- Para reproducción en bucle exacta de un único tema, el agente puede usar el modo loop del reproductor en tu navegador. Si no está disponible, intentará alternativas como el Mix o repetir la pista al finalizar.
- Para colas dinámicas, el agente puede crear una playlist temporal en YouTube y abrirla con autoplay.
## Requisitos de API Key
La API Key necesita las siguientes APIs habilitadas:
- YouTube Data API v3
## Soporte de sistemas operativos
- ✅ Windows
- ✅ macOS
- ✅ Linux
## Licencia
Ver archivo LICENSE
## Contribuciones
Ver archivo CONTRIBUTING.md
