# 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