io.github.arijit-gogoi/mpv-mcp-server
Control mpv media player — playback, playlists, YouTube streaming, and downloads.
Open source Open in the app JSON README (API)
About
Control mpv media player — playback, playlists, YouTube streaming, and downloads.
Details
- Kind
- MCP servers
- Topic
- Social & content
- Publisher
- arijit-gogoi
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.2.0
- Stars
- 1
- Last push
- 2026-04-12T19:07:08Z
- Repository state
- ativo
- Language
- TypeScript
- Added
- 2026-08-29 03:02:26
- Updated
- 2026-08-29 03:02:26
- Origin id
io.github.arijit-gogoi/mpv-mcp-server
README
# mpv-mcp-server
MCP server for controlling [mpv](https://mpv.io) 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](https://mpv.io/installation/)** — media player (must be on your PATH, or set `MPV_PATH`)
- **[Node.js](https://nodejs.org/) 22+**
- **[yt-dlp](https://github.com/yt-dlp/yt-dlp)** *(optional)* — required for YouTube streaming and downloading
- **[ffmpeg](https://ffmpeg.org/)** *(optional)* — required for audio extraction, metadata reading (ffprobe), and tagging
## Quick Start
### Claude Code
Add to your project's `.mcp.json`:
```json
{
"mcpServers": {
"mpv": {
"command": "npx",
"args": ["-y", "mpv-mcp-server"]
}
}
}
```
Or add at user scope (available in all projects):
```bash
claude mcp add mpv --scope user -- npx -y mpv-mcp-server
```
### Claude Desktop
Add to your Claude Desktop config:
```json
{
"mcpServers": {
"mpv": {
"command": "npx",
"args": ["-y", "mpv-mcp-server"]
}
}
}
```
### With environment overrides
```json
{
"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](https://github.com/yt-dlp/yt-dlp) on your PATH. Audio downloads also require [ffmpeg](https://ffmpeg.org/).
### 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](https://ffmpeg.org/) (includes ffprobe).
## How It Works
The server communicates with mpv via its [JSON IPC protocol](https://mpv.io/manual/master/#json-ipc). 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