YouTube MCP MCP Server

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

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

# 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:

{
  "tool": "search_youtube",
  "params": {
    "query": "Bohemian Rhapsody Queen",
    "max_results": 5
  }
}

Con el url del primer resultado devuelto, reproducir:

{
  "tool": "play_youtube",
  "params": {
    "url": "https://www.youtube.com/watch?v=<VIDEO_ID>"
  }
}

Ejemplos avanzados

• Playlist con orden explícito (por IDs conocidos):

  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:

  {
    "tool": "play_youtube",
    "params": {
      "url": "https://www.youtube.com/watch_videos?video_ids=VIDEO1,VIDEO2,VIDEO3,VIDEO4"
    }
  }
  

  Alternativa (menos determinista en algunos navegadores):

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

  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:

  {
    "tool":