Navidrome MCP Server

Transform your Navidrome music server with an AI-powered music assistant. This MCP (Model Context Protocol) server enables Claude, ChatGPT, and other AI assistants to interact with your personal music library through natural language, offering intelligent playlist creation, music discovery, and library management.

Table of Contents

• Why Navidrome MCP?
• Features
  • Music Library Management
  • Intelligent Playlist Creation
  • Personalized Music Discovery
  • Smart Radio Management
  • Analytics & Insights
• Installation
  • Prerequisites
  • Quick Setup
  • Configure Claude Desktop
  • Configure ChatGPT Desktop
• Powerful Usage Examples
• Available Tools
• Troubleshooting
• Development
• License

Why Navidrome MCP?

Imagine having an AI assistant that truly understands your music taste. This MCP server enables AI assistants to:

• Analyze your listening patterns and create perfectly curated playlists
• Discover hidden gems in your library based on your mood or activity
• Build custom radio stations from your favorite tracks
• Find music similar to what you love using Last.fm's recommendation engine
• Discover internet radio stations from around the world with advanced filtering
• Get synchronized lyrics with millisecond-precision timestamps for your favorite tracks
• Manage your library with simple conversational commands

This isn't just another music tool – it's your personal music curator powered by AI.

Features

🎵 Music Library Management

• Intelligent Browsing: Navigate songs, albums, artists, and genres with smart filtering
• Deep Search: Full-text search across all metadata or targeted searches for specific content
• Rich Metadata: Access detailed information about tracks, albums, and artists
• Tag Analysis: Explore and analyze metadata tags (genre, composer, label, year, and more)
• Clean Responses: Optimized data transfer with only essential fields (~10 properties vs 50+ raw)

🎶 Intelligent Playlist Creation

• AI Assistant Integration: Enables AI assistants to analyze your taste and build themed playlists
• Smart Management: Create, update, and organize playlists conversationally
• Flexible Track Addition: Add songs by ID, entire albums, artist discographies, or specific discs
• Dynamic Reordering: Rearrange tracks with simple commands
• Cross-Reference: Find which playlists contain specific songs

🎼 Personalized Music Discovery

• Listening Data Access: Provides listening history data for AI assistants to understand your preferences
• Similar Artist/Track Finding: Discover music similar to your favorites via Last.fm
• Artist Deep Dives: Get biographies, popular tracks, and related artists
• Global Trends: Browse worldwide music charts and trending genres
• Library Analysis Tools: Access data to help AI assistants find overlooked tracks in your library

📻 Smart Radio Management

• Stream Validation: Test radio URLs before adding to avoid broken streams
• Format Detection: Automatic detection of MP3, AAC, OGG, FLAC streams
• Metadata Extraction: Pull station info from SHOUTcast/Icecast headers
• Custom Station Creation: Build radio stations from your collection
• One-Time Setup Tips: Smart contextual help that appears only when needed

🌍 Internet Radio Discovery

• Global Station Database: Access thousands of internet radio stations worldwide via Radio Browser
• Advanced Filtering: Search by genre, country, language, codec, bitrate, and more
• Automatic Validation: Discovered stations are tested for availability
• Quality Control: Filter out broken stations and focus on high-quality streams
• Popularity Metrics: Discover stations by vote count and listener engagement
• Station Management: Tools for AI assistants to add discovered stations to your collection

🎤 Synchronized Lyrics

• Time-Synchronized Lyrics: Get lyrics with millisecond-precision timestamps for line-by-line timing
• Dual Format Support: Access both time-synced and plain text lyrics
• Community-Powered: Lyrics sourced from LRCLIB's community database
• Smart Matching: Automatic matching by title, artist, album, and duration
• No API Keys Required: Free lyrics access without registration

📊 Analytics & Insights

• Listening Patterns: Understand your music habits with play statistics
• Taste Evolution: Track how your preferences change over time
• Most/Least Played: Discover your true favorites and forgotten tracks
• Genre Distribution: Access data about your library's composition for analysis
• Recommendation Data: Provides data for AI assistants to generate suggestions based on your history

⭐ Preference Management

• Star System: Mark favorites for quick access
• 5-Star Ratings: Rate content for better recommendations
• Queue Control: Manage playback queues across devices
• Data Access for Organization: Provides preference data for AI assistants to help organize your collection

Installation

Prerequisites

• Node.js 20+ (Download here)
• Running Navidrome server with your music library
• Claude Desktop or ChatGPT Desktop (or any MCP-compatible client)

Additional for manual build:

• pnpm package manager (Install instructions)

Quick Setup

Method 1: NPM Package (Recommended)

The easiest way to get started is using the published npm package, which auto-updates on launch:

npm install -g navidrome-mcp

📦 Package: navidrome-mcp on npm

This installs the MCP server globally and keeps it up-to-date automatically.

Method 2: Manual Build (Development)

For development or custom builds:

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

Configure Claude Desktop

Find your configuration file:

• Windows: %APPDATA%/Claude/claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Add the Navidrome MCP server:

Using NPM Package (Recommended)

{
  "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", // Optional: Set default active libraries (comma-separated IDs)
        "LASTFM_API_KEY": "your_api_key", // Get your own at https://www.last.fm/api/account/create
        "RADIO_BROWSER_USER_AGENT": "Navidrome-MCP/1.0 (+https://github.com/Blakeem/Navidrome-MCP)",
        "LYRICS_PROVIDER": "lrclib",
        "LRCLIB_USER_AGENT": "Navidrome-MCP/1.0 (+https://github.com/Blakeem/Navidrome-MCP)"
      }
    }
  }
}

Using Manual Build (Alternative)

{
  "mcpServers": {
    "navidrome": {
      "command": "node",
      "args": ["/absolute/path/to/navidrome-mcp/dist/index.js"],
      "env": {
        "NAVIDROME_URL": "http://your-server:4533",
        "NAVIDROME_USERNAME": "your_username",
        "NAVIDROME_PASSWORD": "your_password",
        "NAVIDROME_DEFAULT_LIBRARIES": "1,2", // Optional: Set default active libraries (comma-separated IDs)
        "LASTFM_API_KEY": "your_api_key", // Get your own at https://www.last.fm/api/account/create
        "RADIO_BROWSER_USER_AGENT": "Navidrome-MCP/1.0 (+https://github.com/Blakeem/Navidrome-MCP)",
        "LYRICS_PROVIDER": "lrclib",
        "LRCLIB_USER_AGENT": "Navidrome-MCP/1.0 (+https://github.com/Blakeem/Navidrome-MCP)"
      }
    }
  }
}

Important:

• NPM method: Uses npx navidrome-mcp which auto-updates on each launch
• Manual method: Requires absolute paths (full path from root) and manual updates
• Library filtering: Use NAVIDROME_DEFAULT_LIBRARIES to set default active libraries (e.g., "1" for one library, "1,2,3" for multiple)
  • If not set, all libraries are active by default
  • You can change active libraries at runtime using the set_active_libraries tool
  • Invalid library IDs are ignored with a warning
• Get a free Last.fm API key at Last.fm (optional - enables music discovery)
• Radio Browser integration requires a User-Agent string (enables station discovery)
• Lyrics integration works without API keys (LRCLIB is free)
• Features are automatically enabled/disabled based on available configuration
• Restart Claude Desktop after saving

Configure ChatGPT Desktop

Using NPM Package (Recommended)

1. Open ChatGPT Desktop
2. Go to Settings → Connectors
3. Click Create and add:
   • Command: npx
   • Args: navidrome-mcp
   • Environment variables: Same as above
4. Save and restart

Using Manual Build (Alternative)

1. Open ChatGPT Desktop
2. Go to Settings → Connectors
3. Click Create and add:
   • Command: node
   • Args: /absolute/path/to/navidrome-mcp/dist/index.js
   • Environment variables: Same as above
4. Save and restart

Powerful Usage Examples

🎯 Smart Discovery & Playlist Creation

• "Look at my most played artists, find what albums I'm missing from their discographies, and tell me which ones are most popular"
• **"Create a 'Best of Pink Floyd' playlist using Last.fm's top tracks data, but only with so

---