Navidrome MCP Server

An MCP (Model Context Protocol) server for Navidrome. Claude Desktop, Claude Code, Cursor, and other MCP clients can browse your library, build playlists, discover new music, and play audio through your machine's speakers.

Table of Contents

• Features

• Available Tools

• Installation & Setup

• Troubleshooting

• Development

• License

• Support

Related MCP server: Spotify MCP Server

Features

🎵 Music Library

Browse and search songs, albums, artists, genres, and tags. The filters for query, starred status, a single year, sort order, and tag values combine in one request, such as "all my starred jazz albums from 1994" or "every song tagged Soundtrack with a 5-star rating". Tag analysis tools show what is in your library, so you don't have to guess at filter values.

🔊 Local Audio Playback

Requires mpv on the machine running the MCP server, as mpv Installation describes.

Audio plays through that machine's speakers with no browser or Navidrome web UI. Search and play in one step, such as "play 5 random starred albums", "queue everything I've starred from 1994", or "add 10 random rock songs to whatever's already playing, shuffled". Album playback can shuffle the album order, the tracks, or both.

Reorder or shuffle the queue during playback without interrupting the current song. Saved Navidrome radio stations play through mpv and show the song the station is playing. Plays scrobble back to Navidrome, so play counts and recent activity stay in sync. mpv starts on first use and can keep playing across MCP client restarts, as Player Lifetime describes. Playback works on Linux, macOS, and Windows 11.

A Raspberry Pi or an always-on machine with speech to text (such as Whisper) and text to speech works as a hands-free music player.

🎛️ MPV Remote (Web UI)

Requires mpv.

A web player at http://localhost:8808 controls local playback from any browser. It shows the current song with cover art, transport and seek controls, volume, and a live queue. Click a queue entry to jump to it. Enable Expose on LAN to use the player from a phone or tablet. MPV Remote setup covers setup, lifetime, and security.

The Play Music window searches artists, albums, and songs. An artist expands to its albums, and an album to its songs. The window also starts any playlist, your starred songs, or your starred albums. Each pick adds to the queue or replaces it, with an option to shuffle songs or albums. So the page works as a remote without the assistant.

🌈 Visualizer

The visualizer beside the track info moves with the music. It has 19 styles. Click it to switch to the next style, and the style's name shows for a moment. Each device keeps its own style. The images below show four of them.

🎶 Playlists

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

🎼 Music Discovery (Last.fm)

Requires a Last.fm API key, free at last.fm/api and set in the settings page.

Find similar artists and tracks, read biographies and top tracks, and browse global charts. With your library in the mix, you can ask for missing albums or overlooked music, such as "albums missing from my top 5 artists, ranked by popularity" or "tracks similar to my favorites that I own but never play". You can also build "Best Of" playlists from what you own.

🎤 Synchronized Lyrics

LRCLIB is set in the settings page and needs no API key. Lyrics stored in your files work without it.

Lyrics come from the audio file's tags and from LRCLIB's community database. Timed lyrics take priority over plain text. Within each kind, the file's lyrics come before LRCLIB's.

The web player's lyrics view highlights the current line and scrolls to follow it. Click a line to jump playback there. Scroll to read ahead. Then a button returns the view to the current line. The view fills the page or opens as a window over the player. Font size and sync offset are adjustable, and each device keeps its own choices. The screen stays awake while the view is open and music plays.

📻 Internet Radio

Manage Navidrome radio stations and discover new ones worldwide. create_radio_station checks each stream before adding it when validateBeforeAdd is set. validate_radio_stream checks any public http(s) URL on demand. The checks detect MP3, AAC, OGG, and FLAC streams. They also read SHOUTcast and Icecast metadata. Private, loopback, and link-local addresses are refused. Bulk maintenance works too, such as "validate all my stations and remove the broken ones" or "test these 10 URLs and add the working ones".

Global discovery uses Radio Browser and needs a user agent, set in the settings page. It searches thousands of stations by genre, country, language, codec, bitrate, and popularity. Your votes and clicks count toward Radio Browser's community ranking.

📊 Listening Analytics

See play counts, recent activity, top-rated and most-played lists, and tag distribution across your library. Use them to find forgotten favorites and one-hit wonders, or to build mood playlists from your listening patterns.

⭐ Ratings & Favorites

Star and unstar songs, albums, and artists. Set 0-5 star ratings and list everything starred or top-rated. Read and write the saved queue that Navidrome's own web UI uses to sync across devices.

📚 Multi-Library Support

Filter all operations to a subset of your Navidrome libraries. Set a default in the settings page or switch the active libraries at runtime.

Available Tools

A category with requires in its heading only appears once that setting is filled in.

Core System

Library Management

Search

Playlists

Ratings & Favorites

Listening History & Saved Queue

Metadata & Tags

Last.fm Discovery (requires a Last.fm API key)

Lyrics

Radio Management

Global Radio Discovery (requires a Radio Browser user agent)

Local Playback (requires mpv)

Transcode format in First-run setup sets the stream format.

Installation & Setup

Prerequisites

• Node.js 20.18.1+ (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.

npm install -g navidrome-mcp

Update it later with npm update -g navidrome-mcp.

For a development build, clone and build the repository.

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

MCP Client Configuration

The MCP client config only tells the client how to start the server. Your Navidrome login and every option go in a local settings.json that you edit through the settings page (see First-run setup).

Claude Desktop reads claude_desktop_config.json from %APPDATA%/Claude/ on Windows, ~/Library/Application Support/Claude/ on macOS, or ~/.config/Claude/ on Linux. Add the block below to it. Other MCP clients take the same JSON.

{
  "mcpServers": {
    "navidrome": {
      "command": "npx",
      "args": ["navidrome-mcp"]
    }
  }
}

On native Windows, Claude Code and other clients that start the server without a shell need "command": "cmd" and "args": ["/c", "npx", "navidrome-mcp"].

With a development build, the client runs the built server with node.

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

First-run setup

If nothing is configured yet, the settings page opens in your browser the first time you start the MCP server or the standalone player (navidrome-web). Where a browser can't open, such as over SSH, the URL is printed to the console instead.

On the stdio transport, the MCP server also starts in setup mode when the saved settings fail at startup. In setup mode it offers only the open_settings and test_connection tools, and both return the settings URL and what went wrong. If the settings were rejected, the settings page opens so you can fix them. If Navidrome was unreachable, the page stays closed, since the settings may be fine. Restart the MCP client once Navidrome is back up.

You can open the settings page any time with navidrome-config. Fill in your Navidrome URL, username, and password, then click Test connection and Save. Saving writes settings.json to your config directory. settings.example.json shows the file's shape.

• Windows: %APPDATA%\navidrome-mcp\

• macOS: ~/Library/Application Support/navidrome-mcp/

• Linux: ~/.config/navidrome-mcp/ (or $XDG_CONFIG_HOME/navidrome-mcp/)

These settings are optional.

• Default libraries: comma-separated library IDs to activate by default. Blank means all.

• Last.fm API key: enables Last.fm discovery.

• Radio Browser user agent: enables global station discovery.

• Lyrics provider (LRCLIB) and user agent: enables LRCLIB lyrics.

• mpv path: the mpv binary location if it's not on PATH. Blank auto-detects.

• Transcode format: defaults to raw, which streams the original file for best quality and reliable seeking. Set a codec such as mp3 or opus for slow or metered links. The bitrate applies only when a codec is set.

• Web UI: the MPV Remote settings, listed in Configuration.

• Transport: how MCP clients reach the server, described in HTTP Transport.

Settings load only at startup. To apply a change, quit and reopen the MCP client, or re-run navidrome-web. When upgrading from the old env setup, the form pre-fills from your shell environment and a .env file. The form sees the env block in your MCP client's JSON only when the MCP server opens the settings page itself. Otherwise re-enter those values, or export them in the shell before running navidrome-config.

Headless Machines and Containers

The settings page binds loopback only, so a host with no browser, such as a VPS or a Docker container, uses environment variables instead. When no usable settings.json exists, the server runs from NAVIDROME_URL, NAVIDROME_USERNAME, and NAVIDROME_PASSWORD. These variables set the optional settings.

• LASTFM_API_KEY enables Last.fm discovery.

• RADIO_BROWSER_USER_AGENT (such as Navidrome-MCP) enables radio discovery.

• LYRICS_PROVIDER=lrclib with LRCLIB_USER_AGENT enables LRCLIB lyrics.

• NAVIDROME_DEFAULT_LIBRARIES sets the default library IDs, comma separated.

• MPV_PATH sets the mpv binary location.

• DEBUG=true turns on verbose logs.

HTTP Transport lists the transport variables.

mpv Installation

mpv is a cross-platform media player. The server registers the playback tools when it finds mpv at startup.

macOS (via Homebrew):

brew install mpv

If an MCP client started from the Dock or Finder can't find Homebrew's mpv, set mpv path (playback.mpvPath) to /opt/homebrew/bin/mpv on Apple Silicon or /usr/local/bin/mpv on Intel.

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 ID shinchiro.mpv. Plain winget install mpv prompts you to pick between it and an unofficial Store package. The shinchiro build is the one mpv.io links for Windows.

Windows PATH note. The shinchiro.mpv package installs to C:\Program Files\MPV Player\ and does **not** add itself to PATH. Use one of these fixes.

• Add that folder to your PATH (System Properties → Environment Variables → Path → New), then open a new terminal.

• Set mpv path in the settings page (playback.mpvPath) to the full mpv.exe path, such as C:\Program Files\MPV Player\mpv.exe.

Other install methods (scoop, choco, manual zip) use different folders. If mpv --version fails in a fresh terminal, locate mpv.exe and apply one of the fixes above.

A pre-built binary from mpv.io also works. Verify with mpv --version. Then restart your MCP client so the server finds mpv.

MPV Remote setup

Player Lifetime

The server starts the player as a separate navidrome-web process. The port binds immediately, so the page is reachable before anything plays. Hosts without mpv don't start it. The gear icon in the player opens its settings.

Whether playback keeps going after you close your AI client depends on how the player started.

• Default (off): the MCP-launched player and mpv stop when the last MCP server using them closes or restarts.

• Keep playing after the MCP server closes (webui.persistAfterMcpExit, in the settings page or the gear modal): the player keeps running. Stop it with the power button.

• Launched yourself (navidrome-web, below): always runs independently. The MCP server attaches to it and never shuts it down.

mpv stops when the player stops.

Standalone Player

navidrome-web runs the player without an MCP client.

navidrome-web                # after: npm install -g navidrome-mcp
# or, from a dev clone / manual build:
node dist/web/main.js

It reads settings.json and opens your browser. In a terminal it runs in the foreground. It stops when you close the terminal, press Ctrl+C, or click the power button. The desktop shortcut below runs it in the background. The first process to bind the port runs the player, and any later one attaches to it. Logs go to navidrome-web.log in your config directory.

Desktop Shortcut

Generate a double-clickable icon for your platform. It starts the player in the background with no terminal window and opens your browser. If a player is already running, it only opens the browser.

navidrome-web-shortcut       # after: npm install -g navidrome-mcp
# or, from a dev clone (see Development):
pnpm make:launcher

The shortcut stores the absolute paths to your node and the built player, so neither needs to be on PATH. The generator writes these files.

• Linux: navidrome-player.desktop on your Desktop and in your app menu (~/.local/share/applications). On GNOME, right-click → Allow Launching the first time.

• macOS: Navidrome Player.app on your Desktop, which you can move to /Applications.

• Windows: Navidrome Player.lnk shortcuts on your Desktop and in the Start Menu.

If you move or rebuild the project, run the generator again so the paths stay current.

Configuration

Every setting below except webui.theme is in the Web UI section of the settings page. The gear modal applies persistAfterMcpExit, theme, and visualizer live. Other changes apply after you stop the player with the power button and restart the MCP client or navidrome-web.

Phone and Tablet Remote

1. Enable Expose on LAN in the settings page and Save.

2. Restart the player as Configuration describes.

3. Open the player's Network info dialog to see its LAN URLs, such as http://192.168.1.42:8808. A player run from a terminal also prints them. Open one in your phone's browser and bookmark it.

Security note

The web UI has no authentication. Anyone who can reach the port can use two groups of features.

• Control: playback transport, volume, queue jumps, shuffling, clearing the queue, and starting any library source.

• Read: library search and browsing, recently played history, playlist names, starred counts, cover art, live now-playing and queue state, lyrics of queued songs, and the host's LAN addresses.

Who can reach the port depends on the bind address.

• With webui.host=127.0.0.1 (the default) it's only reachable from the host machine, which is safe.

• With Expose on LAN (webui.expose=true) it's reachable from anything on the LAN. That's fine on a trusted home network. Do not expose it to the public internet. There is no rate limiting. Player settings and the power button stay loopback only, so a phone on your LAN can't change settings or shut the player down. The main settings page is never exposed. Once exposed, GET /healthz returns 404 off the host to avoid leaking a version fingerprint. Check the player's health from its host.

HTTP Transport

By default the client launches the server as a child process and talks to it over stdio. A client on another machine can't reach it.

With the transport set to http, the server listens at /mcp with the MCP Streamable HTTP transport. It runs as a standalone process, and network MCP clients connect to it with no bridge such as supergateway or mcp-proxy.

Add a transport block to your settings.json. host defaults to 127.0.0.1 (loopback only). Set expose: true to bind all interfaces (0.0.0.0) so a remote client can reach it. An explicit host overrides expose. Set authToken to require bearer auth. The settings page has a Generate button for it.

"transport": {
  "type": "http",
  "port": 3000,
  "expose": true,
  "authToken": "a-long-random-secret"
}

Point an HTTP-capable MCP client at http://<host>:<port>/mcp.

{
  "mcpServers": {
    "navidrome": {
      "type": "http",
      "url": "http://your-host:3000/mcp",
      "headers": { "Authorization": "Bearer a-long-random-secret" }
    }
  }
}

When a token is set, every /mcp request must carry Authorization: Bearer <token> (compared in constant time). Anything else gets a 401. If the transport binds a non-loopback address with no token, the server logs a warning at startup. It still starts, so that a deployment locked down by a firewall or NetworkPolicy runs. GET /healthz is an unauthenticated liveness endpoint for container health checks. It returns 200 {"status":"ok"} and makes no Navidrome call.

Host filtering. On the default bind, loopback with no auth token, the server rejects requests whose Host header isn't a loopback name. This blocks DNS rebinding, so a malicious web page can't drive the server through your browser. Setting an authToken or binding a non-loopback address turns the automatic filter off, since a remote deployment is reached by names the server can't know in advance. A lured browser can't attach your token, so the bearer token already blocks rebinding. To pin the accepted names, set transport.allowedHosts, which applies whenever it is present. Each entry is the exact Host header value, with the port when it is not 80 or 443 (such as mcp.example.com:3000). Set transport.allowedOrigins only for browser clients. It gates the Origin header.

The transport also reads MCP_TRANSPORT (stdio or http), MCP_HTTP_HOST, MCP_HTTP_PORT, MCP_HTTP_EXPOSE (true to bind all interfaces), MCP_HTTP_AUTH_TOKEN, MCP_HTTP_ALLOWED_HOSTS, and MCP_HTTP_ALLOWED_ORIGINS from the environment. The last two take comma-separated lists. The web UI has a matching WEBUI_* family (WEBUI_ENABLED, WEBUI_PORT, WEBUI_HOST, WEBUI_EXPOSE, WEBUI_AUTO_OPEN_BROWSER, WEBUI_PERSIST_AFTER_MCP_EXIT, WEBUI_VISUALIZER). These follow the rule in Headless Machines and Containers. They also pre-fill the settings form on first run.

Single account, shared state. One process serves every HTTP session with one Navidrome account. So a set_active_libraries call changes the library filter for every connected session.

Security. The server holds an authenticated Navidrome session, so anyone who reaches an open port controls your library. When the port is reachable beyond loopback, set an auth token or limit access with a firewall, a Kubernetes NetworkPolicy, or a reverse proxy that adds TLS. Keep the default stdio transport unless you need remote access.

Remote playback. Since mpv runs beside the server, HTTP on a machine outside a container gives remote MCP access with working playback.

1. Run the server on the machine wired to your speakers.

2. Point remote clients at http://that-machine:3000/mcp.

3. Set an authToken.

A container gives an always-on endpoint for the library tools with no audio. Running in Docker covers the image, deployment shapes, mounted config, and audio caveats.

ChatGPT Desktop

ChatGPT's MCP support, on the web and desktop, needs a hosted HTTPS endpoint. It does not work with local stdio servers. You can host this server over HTTP Transport behind a reverse proxy that adds TLS, with no bridge such as mcp-remote. A client with stdio support is simpler for a self-hosted music server.

Troubleshooting

Connection problems

• Verify Navidrome is running and reachable.

• Ensure the Navidrome URL in the settings page includes the protocol (http:// or https://).

• Use the settings page's Test connection button before saving. A curl call or a browser also tests the credentials.

macOS

• See the macOS Troubleshooting Guide. The common issue is a client that can't find Node.js, which symlinks or full paths fix.

Configuration

• Use absolute paths in config files.

• Validate the JSON. A trailing comma breaks it.

Desktop shortcut

• If the shortcut opens nothing, read navidrome-web.log beside settings.json (see First-run setup). Fix the settings with navidrome-config, then launch the shortcut again.

Known Limitations

• No audio without mpv. The library tools still work. Use the Navidrome web UI or a Subsonic client to listen (see mpv Installation).

• Recently played shows one play per track. Navidrome stores only each track's last play time.

• The visualizer reads its levels from mpv's log. A future mpv release may change the log format. If the visualizer stops moving after an mpv update, playback still works.

• Saved queue ≠ live queue. The saved-queue tools (get_saved_queue, save_queue, clear_saved_queue) operate on Navidrome's server-side queue (web UI sync). The live-queue tools (get_play_queue, clear_play_queue, shuffle_play_queue, move_in_play_queue, remove_from_play_queue, play_queue_index) operate on the live mpv queue.

Development

Start from the development build in Quick Setup.

node dist/config-app/main.js   # opens the settings page. Fill in and Save.

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

The published package may lag behind the dev branch. pnpm build also copies the web UI's static files into dist/, which the MCP server and the player run from. MPV Remote setup covers running the player and the desktop shortcut from a development build.

Test the tools 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

Custom Visualizers

Each visualizer style is one file in src/webui/public/visualizers/. To add a style, copy _template.js to a new file whose name uses lowercase letters, digits, and dashes. The template lists the rules a style follows. pnpm test:run checks every style against those rules. Then run pnpm build and reload the player page, and the new style joins the click cycle.

License

• Code: AGPL-3.0

• Documentation: CC-BY-SA-4.0

Support

• GitHub Issues

• GitHub Discussions

Built with ❤️ for the Navidrome community