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
• 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 (24 tests, 100% passing)
• 📊 Logging estructurado y centralización de configuración

Instalación

1. Clonar/Crear el proyecto

cd youtube_mcp
# O: git clone https://github.com/roquevaamonde/youtube-mcp.git youtube_mcp

2. Crear el virtual environment

python -m venv venv
source venv/bin/activate  # En Windows: venv\Scripts\activate

3. Instalar dependencias

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:

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:

{
  "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

from youtube_mcp.server import YouTubeMCPServer

server = YouTubeMCPServer(api_key="your_api_key")
results = await server.handle_search_youtube(
    query="Bohemian Rhapsody Queen",
    play=True  # Abre automáticamente en el navegador
)

Tests

pytest tests/

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 (24 tests)
├── 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:

{
  "query": "Bohemian Rhapsody Queen",
  "max_results": 5,
  "play": true
}

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