Navidrome-MCP

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

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

Lyrics (requires the LRCLIB provider, set in the settings page)

Global Radio Discovery (requires a Radio Browser user agent)

Local Playback (requires [`mpv`](https://mpv.io/))

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. Playback streams the original file by default; set Transcode format to a codec for constrained bandwidth (see First-run setup).

Installation

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

First-run setup

On first start without configuration, the settings page opens automatically in your browser. This happens whether you launched the MCP server or the standalone web player (navidrome-web) first; either one, run unconfigured, brings it up. If a browser can't open (e.g. over SSH), the URL is printed to the console, and the unconfigured MCP server also exposes an open_settings tool that returns it. You can open the settings page any time with:

npx navidrome-config

Enter your Navidrome URL, username, and password (plus any optional features), click Test connection, then Save. This writes a local settings.json (shape: settings.example.json). Settings load at startup and don't hot-reload, so restart whatever you launched to apply them: the MCP client (quit and reopen, e.g. Claude Desktop) or the web player (re-run navidrome-web). If the web player brought up the settings page itself, it stays open for further edits and self-closes when idle; re-launch navidrome-web to start playing. Upgrading from the old env-based setup? The form pre-fills from your previous env/.env values; verify and save.

Required: Navidrome URL, username, password.

Optional (set in the settings page): - Default libraries: comma-separated library IDs to activate by default; blank = all. - Last.fm API key: enables Last.fm discovery features. - Radio Browser user agent: enables global station discovery. - Lyrics provider (LRCLIB) + user agent: enables lyrics fetching. - mpv path: point at the mpv binary if it's not on PATH; blank auto-detects. - Transcode format: defaults to raw (streams the original file untouched for best quality and reliable seeking). Set a codec (e.g. mp3, opus) to transcode for slow/metered links; the bitrate applies then. - Web UI (port / host / expose / enabled / auto-open browser): configures the MPV Remote web UI (defaults to localhost:8808).

Features turn on automatically when their settings are present. Restart your MCP client after saving.

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 ID shinchiro.mpv; plain winget install mpv prompts you to disambiguate from an unofficial Store package. The shinchiro build is the one mpv.io points to for Windows. Windows PATH note. The shinchiro.mpv package installs to C:\Program Files\MPV Player\ and does not add itself to PATH. Either: - Add that folder to your PATH (System Properties → Environment Variables → Path → New), then open a new terminal, or - Set mpv path in the settings page (playback.mpvPath) to the full mpv.exe path, e.g. 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.

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

or, from a dev clone / manual build:

node dist/web/main.js ```

Testing the standalone web player from a dev build

This is the from-source path for trying the player before it's published to npm (the published package may lag behind dev). It applies to the MCP server too; both run from the same dist/.

```bash

1. Build (also bundles the web UI's static assets into dist/)

pnpm build

(writes settings.json to your OS config dir; see settings.example.json)

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 ```

Configure Your MCP Client

The MCP client config does just one thing: tell it how to launch the server. Your Navidrome credentials and all options live in a local settings.json, edited through a browser-based settings page (no secrets in the client JSON or environment). The settings page opens automatically on first run (see First-run setup).

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"]
    }
  }
}

For a manual build, replace command/args with:

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

Configuration

All of these are optional and live in the Web UI section of the settings page (navidrome-config); the keys below are their settings.json paths. Restart the client after saving (except persistAfterMcpExit, which the in-player gear modal applies live).

When Expose on LAN is enabled, the player 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.

2. Configure if needed; writes settings.json to your OS config dir

node dist/config-app/main.js # opens the settings page; fill in + Save

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 (or test credentials with curl / a browser) before saving

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