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
- Instalación
- Uso
- Tests
- Calidad de Código
- Estructura del Proyecto
- Herramientas Disponibles
- Ejemplos de Prompts
- Requisitos de API Key
- Soporte de Sistemas Operativos
- Licencia
- 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
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
- Busca "YouTube Data API v3"
- Haz clic en el resultado
- Clic en "Habilitar"
4. **Crear una API Key**:
- Ve a APIs & Services > 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
- Abre las configuraciones de VS Code (
Cmd+Shift+P→ "Preferences: Open User Settings (JSON)") - Localiza o crea la sección
"modelContextProtocol" - 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.pycon 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,tupleen lugar detyping(Python 3.9+) -
Logging estructurado: Setup centralizado con
logger.py -
Constantes: Configuración centralizada en
constants.pypara: - 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
Archivo LICENCE
Contribuciones
Ver archivo CONTRIBUTING.md
