Navidrome MCP Server

Turn your Navidrome music server into a conversational music assistant. This MCP (Model Context Protocol) server lets Claude Desktop, Claude Code, Cursor, and other MCP-compatible clients browse and curate your library, build playlists, discover new music, and play audio directly through your machine's speakers.

Table of Contents

• Features
• Installation
• MPV Remote (Web UI)
• Available Tools
• Troubleshooting
• Development
• License

Features

🎵 Music Library

Browse and search songs, albums, artists, genres, and tags with rich filtering: query, starred status, year range, sort order, tag values, and more. Combine filters to ask things like "all my starred jazz albums from the 90s, sorted by year" or "every song tagged Soundtrack with a 5-star rating". Tag analysis tools surface what's actually in your library so you don't have to guess at filter values.

🔊 Local Audio Playback

Requires mpv on the host running the MCP server (see Installing mpv).

Audio plays through your machine's speakers, no browser or Navidrome web UI needed. Search and play in a single step: "play 5 random starred albums", "queue everything I've starred from the 90s sorted by year", "add 10 random rock songs to whatever's already playing, shuffled". Three shuffle modes for albums (keep order, randomize album order, fully interleave tracks).

The live queue is actively manipulable: move a track to the front and it starts playing, shuffle and the new top plays, remove the current track and the next one auto-advances. Saved Navidrome radio stations (Icecast, SHOUTcast, etc.) stream through mpv with ICY metadata flowing through so you can see what the station is currently playing. Plays scrobble back to Navidrome so your recently-played and play counts stay in sync with what you actually listen to through mpv. mpv is lazy-spawned on first use, survives MCP client restarts via a per-user socket, and works on Linux, macOS, and Windows 11.

This design is built for conversational control and pairs cleanly with voice transports (Whisper STT + TTS) to build a hands-free music device on a Raspberry Pi or always-on machine.

🎛️ MPV Remote (Web Control Panel)

Requires mpv (same as Local Audio Playback). On by default; lazy-binds once playback starts.

A companion web UI at http://localhost:8808 for controlling local mpv playback from any browser. Now-playing card with cover art, transport controls (previous / pause-resume / next), seek bar, volume slider, and a queue list with click-to-jump. Updates live via Server-Sent Events so a phone laid on the desk stays in sync as the assistant feeds the queue. Defaults to localhost-only; flip one env var to expose it on your LAN and use a phone or tablet as a music remote. See MPV Remote (Web UI) for setup and the security note.

🎶 Playlists

Create, update, reorder, and delete playlists conversationally. Add content flexibly in one operation: single songs, entire albums, whole artist discographies, or specific discs. Find which playlists contain a given song. Build dynamic playlists from listening data: "a 'Hidden Gems' playlist of 5-star songs with under 5 plays", "one top track from each album of my top 10 artists, in chronological order".

🎼 Music Discovery (Last.fm)

Requires LASTFM_API_KEY. Free key at last.fm/api.

Find similar artists and tracks, fetch biographies and top tracks, and browse global music charts. Combine with your library to do gap analysis ("albums missing from my top 5 artists, ranked by popularity"), rediscover overlooked music ("tracks similar to my favorites that I own but never play"), or build curated "Best Of" playlists scoped to what you actually own.

🎤 Synchronized Lyrics

Requires LYRICS_PROVIDER=lrclib and LRCLIB_USER_AGENT. No API key needed.

Fetch time-synced lyrics with millisecond-precision timestamps (LRC format) and plain-text fallbacks from LRCLIB's community database. Matched automatically by title, artist, album, and duration.

📻 Internet Radio

Manage Navidrome radio stations and discover new ones globally. Stream URLs are validated before adding (MP3, AAC, OGG, FLAC detection) and SHOUTcast/Icecast metadata is extracted automatically. Bulk maintenance is supported: "validate all my stations and remove the broken ones" or "test these 10 URLs and add the working ones".

Global station discovery via Radio Browser (requires RADIO_BROWSER_USER_AGENT) covers thousands of stations filterable by genre, country, language, codec, bitrate, and popularity, with vote and click registration so your usage feeds the community ranking.

📊 Listening Analytics

Access play counts, recently-played activity, top-rated and most-played listings, and tag distribution across your library. Use this to drive taste analysis ("genres I'm playing more vs. less this year"), discover forgotten favorites, identify one-hit-wonders in your collection, or build mood-based playlists from your listening patterns.

⭐ Ratings & Favorites

Star/unstar songs, albums, and artists, set 0-5 star ratings, and list everything starred or top-rated. Read and write the saved Navidrome queue used by the web UI for cross-device sync.

📚 Multi-Library Support

Filter all operations to a subset of your Navidrome libraries, either by setting a default in your client config (NAVIDROME_DEFAULT_LIBRARIES) or by switching active libraries at runtime.

Installation

Prerequisites

• Node.js 20+ (download)
• A running Navidrome server
• An MCP-compatible client (Claude Desktop, Claude Code, Cursor, or another MCP client with local stdio support)
• Optional: mpv for local audio playback

Quick Setup

Install the published package (auto-updates on launch):

npm install -g navidrome-mcp

Package: navidrome-mcp on npm.

For a development build:

git clone https://github.com/Blakeem/Navidrome-MCP.git
cd Navidrome-MCP
pnpm install
pnpm build

Configure Your MCP Client

For Claude Desktop, edit claude_desktop_config.json (locations: %APPDATA%/Claude/ on Windows, ~/Library/Application Support/Claude/ on macOS, ~/.config/Claude/ on Linux). Other MCP clients use the same JSON shape.

{
  "mcpServers": {
    "navidrome": {
      "command": "npx",
      "args": ["navidrome-mcp"],
      "env": {
        "NAVIDROME_URL": "http://your-server:4533",
        "NAVIDROME_USERNAME": "your_username",
        "NAVIDROME_PASSWORD": "your_password",
        "NAVIDROME_DEFAULT_LIBRARIES": "1,2",
        "LASTFM_API_KEY": "your_api_key",
        "RADIO_BROWSER_USER_AGENT": "Navidrome-MCP/2.0 (+https://github.com/Blakeem/Navidrome-MCP)",
        "LYRICS_PROVIDER": "lrclib",
        "LRCLIB_USER_AGENT": "Navidrome-MCP/2.0 (+https://github.com/Blakeem/Navidrome-MCP)"
      }
    }
  }
}

For a manual build, replace command/args with:

"command": "node",
"args": ["/absolute/path/to/Navidrome-MCP/dist/index.js"]

Required: NAVIDROME_URL, NAVIDROME_USERNAME, NAVIDROME_PASSWORD.

Optional:

• NAVIDROME_DEFAULT_LIBRARIES: comma-separated library IDs to activate by default; omit for all libraries.
• LASTFM_API_KEY: enables Last.fm discovery features.
• RADIO_BROWSER_USER_AGENT: enables Radio Browser global station discovery. Replace the project URL with your own.
• LYRICS_PROVIDER=lrclib + LRCLIB_USER_AGENT: enables lyrics fetching.
• MPV_PATH: point at the mpv binary if it's not on PATH (e.g. "C:\\Program Files\\mpv\\mpv.exe").
• WEBUI_PORT / WEBUI_HOST / WEBUI_EXPOSE / WEBUI_ENABLED: configure the MPV Remote web UI — defaults to localhost:8808 and lazy-binds once mpv is playing.

Features turn on automatically when their config is present. Restart your MCP client after changing the config.

Installing mpv (optional)

mpv is a lightweight, cross-platform media player. When detected at startup, the server registers an additional set of playback tools so audio streams through your machine's speakers. Without it, the server still manages your library and Navidrome's saved queue; it just doesn't produce audio.

macOS (via Homebrew):

brew install mpv

Linux:

sudo apt install mpv       # Debian / Ubuntu / Mint / PopOS
sudo dnf install mpv       # Fedora / RHEL / CentOS Stream
sudo pacman -S mpv         # Arch / Manjaro
sudo zypper install mpv    # openSUSE

Windows:

winget install shinchiro.mpv   # winget is included on Windows 11
scoop install mpv
choco install mpv

Use the full package ID shinchiro.mpv to skip the disambiguation prompt; the Microsoft Store also lists an unofficial third-party mpv package, and plain winget install mpv will ask you to pick. The shinchiro build is the community standard that mpv.io itself points to for Windows.

Windows PATH note. The shinchiro.mpv winget package installs to C:\Program Files\MPV Player\ on Windows 11 and does not add itself to PATH. You have two options:

• Add the install folder to your user or system PATH (System Properties → Environment Variables → Path → New → C:\Program Files\MPV Player), then open a new terminal so the change takes effect.
• Or set MPV_PATH in your MCP client config to the full mpv.exe path, e.g. "MPV_PATH": "C:\\Program Files\\MPV Player\\mpv.exe".

Other install methods (scoop, chocolatey, manual zip from mpv.io) drop mpv.exe in a different folder. If mpv --version doesn't work in a fresh terminal after install, locate mpv.exe and apply one of the two fixes above.

Or a pre-built binary from mpv.io. Verify with mpv --version, then restart your MCP client so the server re-detects mpv.

A Note on ChatGPT Desktop

ChatGPT's MCP support (web and desktop) requires a hosted HTTPS endpoint and is not currently compatible with local stdio servers like this one. If you really want to make it work with ChatGPT, you can wrap a stdio server in HTTPS using a bridge like mcp-remote, but that adds operational complexity for a self-hosted music server. Otherwise, use Claude Desktop, Claude Code, Cursor, or another client with native stdio support. Re-check once OpenAI adds first-party stdio MCP support.

MPV Remote (Web UI)

When local audio playback is active, the MCP server runs a companion web interface that doubles as a now-playing display and a transport-control remote. Open it in any browser on the host (or anywhere on your LAN once exposed).

What it does

• Now-playing card — cover art, title, artist, album, and queue position. A Live indicator confirms the SSE stream is healthy.
• Transport controls — previous / pause-resume / next, with a seek bar showing current position and remaining time.
• Volume slider — drives mpv's internal volume control (independent of your OS volume).
• Queue list — every track in the current mpv queue with title, artist · album, and duration. Click any row to jump to it.
• Live state updates — Server-Sent Events push state changes the instant they happen, throttled to ~1 Hz so the progress bar runs smoothly without flooding the network. Connections auto-reconnect on disconnect.

Enabling

The web UI is on by default and binds lazily: the port only opens once mpv has something playing, OR when the server reattaches to a pre-existing mpv queue across MCP restarts. Hosts without mpv installed see no listener at all.

To turn it off entirely, set WEBUI_ENABLED=false in your MCP client's env block.

Configuration

All variables are optional. Add them alongside NAVIDROME_URL etc. in your MCP client's env block, then restart the client.

| Variable | Default | Effect | |---|---|---| | WEBUI_ENABLED | true | Set to false to disable the panel entirely. | | WEBUI_PORT | 8808 | Port the HTTP server listens on. Pick a free port if 8808 is taken on your host. | | WEBUI_HOST | 127.0.0.1 | Bind address. Override only if you know which interface you want — usually WEBUI_EXPOSE is the right knob. | | WEBUI_EXPOSE | false | Set to true to bind on 0.0.0.0 so other devices on your LAN can reach the panel. |

When WEBUI_EXPOSE=true, the MCP server logs the LAN URLs it's reachable on at bind time (e.g. http://192.168.1.42:8808). Open one of those on your phone or tablet.

Using it as a phone/tablet remote

1. Set "WEBUI_EXPOSE": "true" in your MCP client's env block.
2. Restart the MCP client.
3. Trigger any playback (e.g. ask the assistant to "play all my starred songs") — this is what causes the web UI to bind.
4. Open the LAN URL from the startup log on your phone's browser. Bookmark it for one-tap access — the page is a single static HTML/CSS/JS bundle, no install required.

Security note

The web UI has no authentication — anyone who can reach the port can pause, skip, seek, change volume, and jump around the queue.

• On WEBUI_HOST=127.0.0.1 (the default) it's only reachable from the host machine, which is safe.
• On WEBUI_EXPOSE=true it's reachable from anything on the LAN. That's usually fine on a trusted home network, but do not expose it directly to the public internet. There's no rate-limiting, no auth, and the control API allows queue manipulation.

Available Tools

Tools marked conditional are only registered when the corresponding configuration is present.

Core System

| Tool | Description | |------|-------------| | test_connection | Verify Navidrome connectivity and report feature/tool availability |

Library Management

| Tool | Description | |------|-------------| | get_song | Detailed song metadata by ID | | get_album | Detailed album metadata by ID | | get_artist | Detailed artist metadata by ID | | get_song_playlists | List all playlists containing a given song | | get_user_details | User profile, available libraries, and active-library status | | set_active_libraries | Set which libraries are active for all search/list operations |

Search

| Tool | Description | |------|-------------| | search_all | Search across artists, albums, and songs with filters and sorting | | search_songs | Search songs with advanced filters and sorting | | search_albums | Search albums with advanced filters and sorting | | search_artists | Search artists with advanced filters and sorting |

Playlists

| Tool | Description | |------|-------------| | list_playlists | View all accessible playlists | | get_playlist | Get playlist metadata by ID | | create_playlist | Create a new playlist | | update_playlist | Update name, description, or visibility | | delete_playlist | Delete a playlist | | get_playlist_tracks | Get playlist contents (JSON or M3U) | | add_tracks_to_playlist | Add songs, albums, artist discographies, or specific discs in one operation | | remove_tracks_from_playlist | Remove tracks by position | | reorder_playlist_track | Move a track to a new position |

Ratings & Favorites

| Tool | Description | |------|-------------| | star_item | Star a song, album, or artist | | unstar_item | Remove a star | | set_rating | Set a 0-5 star rating | | list_starred_items | View starred songs, albums, or artists | | list_top_rated | View highest-rated items |

Listening History & Saved Queue

| Tool | Description | |------|-------------| | list_recently_played | Recent listening activity with optional time-range filter | | list_most_played | Most-played songs, albums, or artists | | get_saved_queue | Read the Navidrome saved queue (web UI sync) | | save_queue | Save a queue to Navidrome for web UI sync | | clear_saved_queue | Clear the Navidrome saved queue |

Metadata & Tags

| Tool | Description | |------|-------------| | search_by_tags | Search by tag values (genre, releasetype, media, etc.) | | get_tag_distribution | Tag usage counts across the library | | get_filter_options | Discover available filter values for search operations |

Last.fm Discovery (requires LASTFM_API_KEY)

| Tool | Description | |------|-------------| | get_similar_artists | Find artists similar to a given artist | | get_similar_tracks | Find tracks similar to a given track | | get_artist_info | Artist biography and tags | | get_top_tracks_by_artist | Top tracks for an artist | | get_trending_music | Trending artists, tracks, and tags from Last.fm charts |

Lyrics (requires LYRICS_PROVIDER=lrclib + LRCLIB_USER_AGENT)

| Tool | Description | |------|-------------| | get_lyrics | Time-synced (LRC) and plain-text lyrics, matched by title/artist/album/duration |

Radio Management

| Tool | Description | |------|-------------| | list_radio_stations | List all saved Navidrome radio stations | | get_radio_station | Detailed info for a station by ID | | create_radio_station | Create one or more stations (JSON array, optional validateBeforeAdd) | | delete_radio_station | Delete a station | | validate_radio_stream | Test an http(s) stream URL for accessibility and audio content |

Global Radio Discovery (requires RADIO_BROWSER_USER_AGENT)

| Tool | Description | |------|-------------| | discover_radio_stations | Find stations globally via Radio Browser | | get_radio_filters | Available filter values (tags, countries, languages, codecs) | | get_station_by_uuid | Detailed Radio Browser station info | | click_station | Register a play click for popularity metrics | | vote_station | Vote for a station |

Local Playback (requires mpv)

Audio plays through the host's speakers. mpv is lazy-spawned on first use and survives MCP client restarts via a per-user IPC socket.

| Tool | Description | |------|-------------| | play_songs | Play one or many songs; mode: 'replace' \| 'append', optional shuffle | | play_albums | Play one or many albums; mode plus shuffle: 'none' \| 'albums' \| 'songs' (preserve, randomize album order, or fully interleave) | | play_albums_search | One-shot filter-driven album playback; accepts all search_albums filters plus mode/shuffle | | play_songs_search | One-shot filter-driven song playback; accepts all search_songs filters plus mode/shuffle | | play_playlist | One-shot load every track of a Navidrome playlist into the queue by playlistId; supports mode and shuffle | | play_radio_station | Play a saved Navidrome radio station; replaces the queue (mutually exclusive with songs/albums) | | pause | Pause playback (position preserved) | | resume | Resume playback | | next | Skip to the next track | | previous | Skip to the previous track | | seek | Move within the current track (absolute or relative) | | set_volume | Set mpv's internal volume (0-100) | | now_playing | Current title/artist/album/position/duration and queue index (or station + ICY metadata for radio) | | playback_status | Engine health probe (running, mpv version, idle) without spawning mpv | | get_play_queue | Snapshot of the live queue with metadata and current-track index | | clear_play_queue | Clear the queue and stop playback | | shuffle_play_queue | Randomize queue order (membership unchanged) | | move_in_play_queue | Move a queue entry between indices | | remove_from_play_queue | Remove an entry; mpv auto-advances if the current track is removed | | play_queue_index | Jump directly to the queue entry at the given index; does not reorder |

Troubleshooting

Connection problems

• Verify Navidrome is running and reachable
• Ensure NAVIDROME_URL includes the protocol (http:// or https://)
• Test credentials with curl or a browser first

macOS-specific

• See the macOS Troubleshooting Guide (commonly: Node.js path not found; fix with symlinks or full paths)

Configuration

• Use absolute paths in config files
• Validate JSON (no trailing commas)
• Restart your MCP client after changes

Known Limitations

• No audio without mpv. When mpv isn't installed the library and saved-queue tools still work, but audio playback isn't available; use the Navidrome web UI or a Subsonic client.
• Recently-played has no timestamps. Navidrome exposes play counts and completion status, not last-played times.
• Saved queue ≠ live queue. The *_saved_queue tools operate on Navidrome's server-side advisory queue (web UI sync). The *_play_queue tools operate on the local mpv playlist. They are independent.

Development

git clone https://github.com/Blakeem/Navidrome-MCP.git
cd Navidrome-MCP
cp .env.example .env
# Edit .env with your credentials

pnpm dev          # hot reload
pnpm test         # watch-mode tests
pnpm test:run     # one-shot tests
pnpm check:all    # lint + typecheck + dead-code
pnpm build        # production bundle

Testing with MCP Inspector:

pnpm build
npx @modelcontextprotocol/inspector node dist/index.js                  # web UI
npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name search_all --tool-arg query="jazz"    # CLI

License

• Code: AGPL-3.0
• Documentation: CC-BY-SA-4.0

Support

• GitHub Issues
• GitHub Discussions

Built with ❤️ for the Navidrome community