{
  "markdown": "# mpv-mcp-server\n\nMCP 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.\n\n## Prerequisites\n\n- **[mpv](https://mpv.io/installation/)** — media player (must be on your PATH, or set `MPV_PATH`)\n- **[Node.js](https://nodejs.org/) 22+**\n- **[yt-dlp](https://github.com/yt-dlp/yt-dlp)** *(optional)* — required for YouTube streaming and downloading\n- **[ffmpeg](https://ffmpeg.org/)** *(optional)* — required for audio extraction, metadata reading (ffprobe), and tagging\n\n## Quick Start\n\n### Claude Code\n\nAdd to your project's `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"mpv\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mpv-mcp-server\"]\n    }\n  }\n}\n```\n\nOr add at user scope (available in all projects):\n\n```bash\nclaude mcp add mpv --scope user -- npx -y mpv-mcp-server\n```\n\n### Claude Desktop\n\nAdd to your Claude Desktop config:\n\n```json\n{\n  \"mcpServers\": {\n    \"mpv\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mpv-mcp-server\"]\n    }\n  }\n}\n```\n\n### With environment overrides\n\n```json\n{\n  \"mcpServers\": {\n    \"mpv\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mpv-mcp-server\"],\n      \"env\": {\n        \"MPV_PATH\": \"/usr/local/bin/mpv\",\n        \"MPV_MEDIA_DIRS\": \"/home/user/Music,/home/user/Podcasts\",\n        \"MPV_DOWNLOAD_DIR\": \"/home/user/Music\"\n      }\n    }\n  }\n}\n```\n\n## Configuration\n\nAll configuration is via environment variables. Everything has sensible defaults.\n\n| Variable | Default | Description |\n|---|---|---|\n| `MPV_PATH` | `mpv` | Path to mpv executable |\n| `MPV_IPC_PATH` | `\\\\.\\pipe\\mpvpipe` (Windows) or `/tmp/mpv-ipc.sock` (Unix) | IPC socket path |\n| `MPV_MEDIA_DIRS` | `~/Music,~/Videos` | Comma-separated media directories to scan |\n| `MPV_DOWNLOAD_DIR` | `~/Downloads` | Where downloaded files are saved |\n\n## Tools\n\n### Playback\n\n| Tool | Description |\n|---|---|\n| `mpv_play` | Play a file by path or search term |\n| `mpv_pause` | Pause playback |\n| `mpv_resume` | Resume playback |\n| `mpv_stop` | Stop playback |\n| `mpv_status` | Get current playback status |\n| `mpv_seek` | Seek to position (`\"90\"`, `\"1:30\"`, `\"+10\"`, `\"-30\"`) |\n| `mpv_volume` | Get or set volume (0-150) |\n\n### Library\n\n| Tool | Description |\n|---|---|\n| `mpv_browse` | List and search available media files |\n| `mpv_playlist` | Show current playlist |\n| `mpv_add` | Add a track to the playlist |\n| `mpv_load_playlist` | Load a playlist file (.m3u, .pls, .txt) |\n| `mpv_next` | Skip to next track |\n| `mpv_prev` | Go to previous track |\n\n### YouTube\n\n| Tool | Description |\n|---|---|\n| `mpv_youtube` | Search YouTube and stream through mpv (supports append mode) |\n| `mpv_download` | Download from YouTube (audio or video) |\n\nYouTube tools require [yt-dlp](https://github.com/yt-dlp/yt-dlp) on your PATH. Audio downloads also require [ffmpeg](https://ffmpeg.org/).\n\n### Metadata\n\n| Tool | Description |\n|---|---|\n| `mpv_info` | Get metadata for the current track or any file by search term |\n| `mpv_tag` | Write metadata tags (artist, title, album, genre, date, comment) to a file |\n\nBoth tools infer artist/title from the \"Artist - Title\" filename pattern. Requires [ffmpeg](https://ffmpeg.org/) (includes ffprobe).\n\n## How It Works\n\nThe 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.\n\n## Platform Support\n\nDeveloped and tested on **Windows**. macOS/Linux support is implemented but untested — issues and PRs welcome!\n\n## License\n\nMIT\n",
  "bytes": 3763,
  "sha": "c10258e89e1091f90b7617451d07b34470a1021a85f89d12bf8d180706df62e2",
  "repo_slug": "arijit-gogoi/mpv-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_arijit_gogoi_mpv_mcp_server_0ef6cb96/readme"
}