mpv-mcp-server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mpv-mcp-server play 'Bohemian Rhapsody' from my library"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-serverClaude 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 |
|
| Path to mpv executable |
|
| IPC socket path |
|
| Comma-separated media directories to scan |
|
| Where downloaded files are saved |
Tools
Playback
Tool | Description |
| Play a file by path or search term |
| Pause playback |
| Resume playback |
| Stop playback |
| Get current playback status |
| Seek to position ( |
| Get or set volume (0-150) |
Library
Tool | Description |
| List and search available media files |
| Show current playlist |
| Add a track to the playlist |
| Load a playlist file (.m3u, .pls, .txt) |
| Skip to next track |
| Go to previous track |
YouTube
Tool | Description |
| Search YouTube and stream through mpv (supports append mode) |
| Download from YouTube (audio or video) |
YouTube tools require yt-dlp on your PATH. Audio downloads also require ffmpeg.
Metadata
Tool | Description |
| Get metadata for the current track or any file by search term |
| 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 toolsmpv_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 LibraryARead-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 InfoARead-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 PlaybackAIdempotent
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 PlaylistARead-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 PlaybackAIdempotent
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 StatusARead-onlyIdempotent
Get current mpv playback status: track title, position, duration, volume, and pause state.
Inputs: no named parameters.
mpv_stopStop PlaybackADestructiveIdempotent
Stop playback and clear the current file. The playlist is preserved.
Inputs: no named parameters.
mpv_tagTag FileAIdempotent
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 VolumeAIdempotent
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
Scored across 17 tools
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.
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.
With 17 tools, this server covers playback, playlist management, metadata, and downloading/streaming. The number feels appropriate for the domain without being overwhelming.
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
Related MCP Connectors
MCP server for Producer/Riffusion AI music generation
MCP server for Yoto: manage cards, tracks, icons and family devices from any MCP client.
MCP server for Clipkit — gives AI agents a video toolbox via the Clipkit schema.
Remote MCP server for audio stem separation, denoise, reverb, and MIDI export.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server that enables AI agents to play and control YouTube and TikTok videos through a native mpv player window. It supports browsing subscriptions, searching content, managing playlists, and fetching video metadata using authenticated browser cookies.236 npm4MIT
- AlicenseAqualityDmaintenanceControl mpv media player through AI conversation. Play music and video, manage playlists — all via natural language. Works with opencode and any MCP-compatible AI tool.1613 npmMIT
- AlicenseNot gradedqualityDmaintenanceA full-featured YouTube Music MCP server that lets AI assistants control playback, browse history, download songs, and manage playlists via natural language.1ISC
- AlicenseAqualityDmaintenanceMCP server that enables natural language control of internet radio from Claude Code, with access to 30,000+ global stations, auto-playback via mpv, and a real-time status line with audio spectrum visualization.7MIT