mpv-mcp-server

mpv-mcp-server

Servidor MCP para controlar el reproductor multimedia mpv. Explora tu biblioteca de música, controla la reproducción, transmite desde YouTube y descarga pistas, todo desde un cliente MCP como Claude Code.

Requisitos previos

• mpv — reproductor multimedia (debe estar en tu PATH, o establecer MPV_PATH)
• Node.js 22+
• yt-dlp (opcional) — requerido para transmisión y descarga desde YouTube
• ffmpeg (opcional) — requerido para extracción de audio, lectura de metadatos (ffprobe) y etiquetado

Inicio rápido

Claude Code

Añade a .mcp.json de tu proyecto:

{
  "mcpServers": {
    "mpv": {
      "command": "npx",
      "args": ["-y", "mpv-mcp-server"]
    }
  }
}

O añade a nivel de usuario (disponible en todos los proyectos):

claude mcp add mpv --scope user -- npx -y mpv-mcp-server

Claude Desktop

Añade a tu configuración de Claude Desktop:

{
  "mcpServers": {
    "mpv": {
      "command": "npx",
      "args": ["-y", "mpv-mcp-server"]
    }
  }
}

Con anulaciones de entorno

{
  "mcpServers": {
    "mpv": {
      "command": "npx",
      "args": ["-y", "mpv-mcp-server"],
      "env": {
        "MPV_PATH": "/usr/local/bin/mpv",
        "MPV_MEDIA_DIRS": "/home/user/Music,/home/user/Podcasts",
        "MPV_DOWNLOAD_DIR": "/home/user/Music"
      }
    }
  }
}

Configuración

Toda la configuración se realiza mediante variables de entorno. Todo tiene valores predeterminados sensatos.

Variable	Predeterminado	Descripción
MPV_PATH	mpv	Ruta al ejecutable de mpv
MPV_IPC_PATH	\\.\pipe\mpvpipe (Windows) o /tmp/mpv-ipc.sock (Unix)	Ruta del socket IPC
MPV_MEDIA_DIRS	~/Music,~/Videos	Directorios de medios separados por comas para escanear
MPV_DOWNLOAD_DIR	~/Downloads	Dónde se guardan los archivos descargados

Herramientas

Reproducción

Herramienta	Descripción
mpv_play	Reproducir un archivo por ruta o término de búsqueda
mpv_pause	Pausar la reproducción
mpv_resume	Reanudar la reproducción
mpv_stop	Detener la reproducción
mpv_status	Obtener el estado actual de la reproducción
mpv_seek	Buscar posición ("90", "1:30", "+10", "-30")
mpv_volume	Obtener o establecer el volumen (0-150)

Biblioteca

Herramienta	Descripción
mpv_browse	Listar y buscar archivos multimedia disponibles
mpv_playlist	Mostrar la lista de reproducción actual
mpv_add	Añadir una pista a la lista de reproducción
mpv_load_playlist	Cargar un archivo de lista de reproducción (.m3u,.pls,.txt)
mpv_next	Saltar a la siguiente pista
mpv_prev	Ir a la pista anterior

YouTube

Herramienta	Descripción
mpv_youtube	Buscar en YouTube y transmitir a través de mpv (admite modo de anexar)
mpv_download	Descargar desde YouTube (audio o video)

Las herramientas de YouTube requieren yt-dlp en tu PATH. Las descargas de audio también requieren ffmpeg.

Metadatos

Herramienta	Descripción
mpv_info	Obtener metadatos de la pista actual o de cualquier archivo por término de búsqueda
mpv_tag	Escribir etiquetas de metadatos (artista, título, álbum, género, fecha, comentario) en un archivo

Ambas herramientas infieren artista/título del patrón de nombre de archivo "Artista - Título". Requiere ffmpeg (incluye ffprobe).

Cómo funciona

El servidor se comunica con mpv a través de su protocolo JSON IPC. En Windows esto usa una tubería con nombre, en macOS/Linux un socket de dominio Unix. Si mpv no está en ejecución, el servidor lo inicia automáticamente en modo inactivo. El proceso de mpv está separado, por lo que sigue reproduciendo incluso si el servidor MCP se cierra.