mpv-mcp-server

mpv-mcp-server

Servidor MCP para controlar o player de mídia mpv. Navegue pela sua biblioteca de músicas, controle a reprodução, faça streaming do YouTube e baixe faixas — tudo de dentro de um cliente MCP como o Claude Code.

Pré-requisitos

• mpv — player de mídia (deve estar no seu PATH, ou defina MPV_PATH)
• Node.js 22+
• yt-dlp (opcional) — necessário para streaming e download do YouTube
• ffmpeg (opcional) — necessário para extração de áudio, leitura de metadados (ffprobe) e marcação

Início Rápido

Claude Code

Adicione ao .mcp.json do seu projeto:

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

Ou adicione no escopo do usuário (disponível em todos os projetos):

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

Claude Desktop

Adicione à configuração do seu Claude Desktop:

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

Com substituições de ambiente

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

Configuração

Toda a configuração é feita por variáveis de ambiente. Tudo tem padrões sensatos.

Variável	Padrão	Descrição
MPV_PATH	mpv	Caminho para o executável do mpv
MPV_IPC_PATH	\\.\pipe\mpvpipe (Windows) ou /tmp/mpv-ipc.sock (Unix)	Caminho do socket IPC
MPV_MEDIA_DIRS	~/Music,~/Videos	Diretórios de mídia separados por vírgula para escanear
MPV_DOWNLOAD_DIR	~/Downloads	Onde os arquivos baixados são salvos

Ferramentas

Reprodução

Ferramenta	Descrição
mpv_play	Reproduzir um arquivo por caminho ou termo de busca
mpv_pause	Pausar a reprodução
mpv_resume	Retomar a reprodução
mpv_stop	Parar a reprodução
mpv_status	Obter o status atual da reprodução
mpv_seek	Avançar para a posição ("90", "1:30", "+10", "-30")
mpv_volume	Obter ou definir o volume (0-150)

Biblioteca

Ferramenta	Descrição
mpv_browse	Listar e buscar arquivos de mídia disponíveis
mpv_playlist	Mostrar a playlist atual
mpv_add	Adicionar uma faixa à playlist
mpv_load_playlist	Carregar um arquivo de playlist (.m3u, .pls, .txt)
mpv_next	Pular para a próxima faixa
mpv_prev	Voltar para a faixa anterior

YouTube

Ferramenta	Descrição
mpv_youtube	Buscar no YouTube e transmitir pelo mpv (suporta modo de anexar)
mpv_download	Baixar do YouTube (áudio ou vídeo)

As ferramentas do YouTube exigem yt-dlp no seu PATH. Downloads de áudio também exigem ffmpeg.

Metadados

Ferramenta	Descrição
mpv_info	Obter metadados da faixa atual ou de qualquer arquivo por termo de busca
mpv_tag	Escrever tags de metadados (artista, título, álbum, gênero, data, comentário) em um arquivo

Ambas as ferramentas inferem artista/título a partir do padrão de nome de arquivo "Artista - Título". Requer ffmpeg (inclui ffprobe).

Como Funciona

O servidor se comunica com o mpv via seu protocolo JSON IPC. No Windows, isso usa um pipe nomeado; no macOS/Linux, um socket de domínio Unix. Se o mpv não estiver em execução, o servidor o inicia automaticamente em modo ocioso. O processo do mpv é destacado, então ele continua reproduzindo mesmo se o servidor MCP for encerrado.