mpv-mcp-server

mpv-mcp-server

MCP server for controlling mpv media player. Browse your music library, control playback, stream from YouTube, and download tracks — all from inside an MCP client like Claude Code.

Prerequisites

• mpv — media player (must be on your PATH, or set MPV_PATH)
• Node.js 22+
• yt-dlp (optional) — required for YouTube streaming and downloading
• ffmpeg (optional) — required for audio extraction, metadata reading (ffprobe), and tagging

Quick Start

Claude Code

Add to your project's .mcp.json:

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

Or add at user scope (available in all projects):

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

Claude Desktop

Add to your Claude Desktop config:

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

With environment overrides

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

Configuration

All configuration is via environment variables. Everything has sensible defaults.

Variable	Default	Description
MPV_PATH	mpv	Path to mpv executable
MPV_IPC_PATH	\\.\pipe\mpvpipe (Windows) or /tmp/mpv-ipc.sock (Unix)	IPC socket path
MPV_MEDIA_DIRS	~/Music,~/Videos	Comma-separated media directories to scan
MPV_DOWNLOAD_DIR	~/Downloads	Where downloaded files are saved

Tools

Playback

Tool	Description
mpv_play	Play a file by path or search term
mpv_pause	Pause playback
mpv_resume	Resume playback
mpv_stop	Stop playback
mpv_status	Get current playback status
mpv_seek	Seek to position ("90", "1:30", "+10", "-30")
mpv_volume	Get or set volume (0-150)

Library

Tool	Description
mpv_browse	List and search available media files
mpv_playlist	Show current playlist
mpv_add	Add a track to the playlist
mpv_load_playlist	Load a playlist file (.m3u,.pls,.txt)
mpv_next	Skip to next track
mpv_prev	Go to previous track

YouTube

Tool	Description
mpv_youtube	Search YouTube and stream through mpv (supports append mode)
mpv_download	Download from YouTube (audio or video)

YouTube tools require yt-dlp on your PATH. Audio downloads also require ffmpeg.

Metadata

Tool	Description
mpv_info	Get metadata for the current track or any file by search term
mpv_tag	Write metadata tags (artist, title, album, genre, date, comment) to a file

Both tools infer artist/title from the "Artist - Title" filename pattern. Requires ffmpeg (includes ffprobe).

How It Works

The server communicates with mpv via its JSON IPC protocol. On Windows this uses a named pipe, on macOS/Linux a Unix domain socket. If mpv isn't running, the server spawns it automatically in idle mode. The mpv process is detached, so it keeps playing even if the MCP server exits.