Skip to main content
Glama

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

Related MCP server: mcp-mpv-player

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.

Platform Support

Developed and tested on Windows. macOS/Linux support is implemented but untested — issues and PRs welcome!

License

MIT

Available Tools

17 tools
mpv_addAdd to PlaylistA

Add a file to the playlist by path or search term. Use mode "append-play" to start playing it immediately.

Inputs: query (required), mode.

mpv_browseBrowse Music LibraryA
Read-onlyIdempotent

List available music and video files. Optionally filter by search term or directory.

Inputs: search, directory, limit.

mpv_downloadDownload from YouTubeA

Download audio or video from YouTube. Specify format: "audio" for MP3, "video" for full video.

Inputs: query (required), format (required).

mpv_infoTrack InfoA
Read-onlyIdempotent

Get metadata (artist, title, album, genre, etc.) for a file by search term, or the currently playing track if omitted.

Inputs: query.

mpv_load_playlistLoad Playlist FileA

Load a playlist file (.txt, .m3u). Omit path to list available playlists.

Inputs: path, mode.

mpv_nextNext TrackA

Skip to the next track in the playlist.

Inputs: no named parameters.

mpv_pausePause PlaybackA
Idempotent

Pause the currently playing track.

Inputs: no named parameters.

mpv_playPlay Music/VideoA

Play a file by path or search term. Searches your Music and Videos folders when given a name like "sultans of swing".

Inputs: query (required).

mpv_playlistShow PlaylistA
Read-onlyIdempotent

Show the current playlist with track numbers and the active track marked.

Inputs: no named parameters.

mpv_prevPrevious TrackA

Go back to the previous track in the playlist.

Inputs: no named parameters.

mpv_resumeResume PlaybackA
Idempotent

Resume playback if paused.

Inputs: no named parameters.

mpv_seekSeekA

Seek to a position. Accepts seconds ("90"), timestamp ("1:30"), or relative ("+10", "-30").

Inputs: target (required).

mpv_statusmpv StatusA
Read-onlyIdempotent

Get current mpv playback status: track title, position, duration, volume, and pause state.

Inputs: no named parameters.

mpv_stopStop PlaybackA
DestructiveIdempotent

Stop playback and clear the current file. The playlist is preserved.

Inputs: no named parameters.

mpv_tagTag FileA
Idempotent

Write metadata tags to a media file using ffmpeg. Can target a file by search term. Infers artist/title from the filename if not provided.

Inputs: query (required), artist, title, album, +3 more.

mpv_volumeGet/Set VolumeA
Idempotent

Get or set the playback volume. Provide a level (0-150) to set, or omit to get current volume.

Inputs: level.

mpv_youtubePlay from YouTubeA

Search YouTube and stream the result through mpv. Accepts a search query or a direct YouTube URL.

Inputs: query (required), results, mode.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 17 tools

    Disambiguation4/5

    Most tools have distinct purposes, but mpv_play and mpv_add have some overlap since both can start playback; however, descriptions clarify the difference (play vs. append). Overall clearly distinguishable.

    Naming Consistency5/5

    All tools follow a consistent mpv_verb pattern (e.g., mpv_play, mpv_seek). The only minor exception is 'mpv_playlist' (noun only), but it's still predictable.

    Tool Count5/5

    With 17 tools, this server covers playback, playlist management, metadata, and downloading/streaming. The number feels appropriate for the domain without being overwhelming.

    Completeness4/5

    The tool surface is comprehensive for basic media player control and metadata editing. Missing features like shuffle, repeat, or playlist editing are minor gaps for a typical use case.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers