Navidrome MCP

🚀 Navidrome MCP Server

Transform your Navidrome music server into an intelligent hub with an AI-powered music assistant. This MCP (Model Context Protocol) server empowers AI assistants like Claude, ChatGPT, etc., to interact with your personal music library via natural language. It offers intelligent playlist creation, music discovery, and efficient library management.

🚀 Quick Start

The Navidrome MCP Server allows AI assistants to interact with your Navidrome music library. With it, you can analyze listening patterns, create playlists, discover new music, and manage your library using natural language. To get started, follow the installation steps below.

✨ Features

🎵 Music Library Management

• Intelligent Browsing: Navigate through songs, albums, artists, and genres using smart filtering.
• Deep Search: Conduct full - text searches 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 such as genre, composer, label, year, etc.
• Clean Responses: Optimize data transfer with only essential fields (~10 properties instead of 50+ raw).

🎶 Intelligent Playlist Creation

• AI Assistant Integration: Enable AI assistants to analyze your taste and build themed playlists.
• Smart Management: Create, update, and organize playlists through conversations.
• 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: Provide 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: Automatically detect 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: Receive smart contextual help 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, etc.
• Automatic Validation: Test discovered stations 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: Provide 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: Source lyrics from LRCLIB's community database.
• Smart Matching: Automatically match by title, artist, album, and duration.
• No API Keys Required: Access free lyrics without registration.

📊 Analytics & Insights

• Listening Patterns: Understand your music habits through 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: Provide 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: Provide preference data for AI assistants to help organize your collection.

📦 Installation

Prerequisites

• Node.js 20+ (Download here)
• A 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 start is by 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",
        "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",
        "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.
• 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

💻 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 songs I actually own"
• "Analyze my recently played songs, find similar tracks in my library I haven't played in 6 months, and create a rediscovery playlist"
• "Build me a playlist mixing my top 10 most played songs with similar tracks from artists I own but rarely listen to"

🔍 Collection Gap Analysis

• "Show me which albums are missing from my top 5 most played artists and rank them by Last.fm popularity"
• "Find artists where I only own singles or compilations, not their main albums"
• "Identify my favorite genres, then show me highly - rated albums in those genres that I don't own"
• "Look at artists similar to my favorites and tell me which ones I already have in my library but never play"

📻 Radio Station Maintenance

• "Go through all my existing radio stations, validate each one, and remove the broken ones"
• "Here are 10 jazz radio URLs I found online - test them all and add only the working ones with good bitrates"
• "Find the top - voted jazz and classical stations worldwide, validate them, and add the best 5 of each genre"
• "Check all my radio stations and replace any broken ones with similar working stations"

🎼 Advanced Playlist Automation

• "Create a 'Hidden Gems' playlist with 5 - star rated songs that have less than 5 plays"
• "Build weekly playlists based on what I listened to most each month of last year"
• "Make a 'Complete Artist Journey' playlist with one top track from each album of my top 10 artists, in chronological order"
• "Generate mood playlists by analyzing my listening patterns: what I play in mornings vs evenings vs weekends"

📊 Listening Insights & Organization

• "Analyze my jazz collection: show play counts, ratings, and find which albums I've never fully listened to"
• "Find duplicate songs across different albums and create a cleanup list"
• "Show me my listening evolution: which genres I've moved away from and which I'm playing more"
• "Identify 'one - hit wonders' in my library - artists where I only play one song repeatedly"

Available Tools

🔧 Core System

📚 Library Management

🔍 Search & Discovery

🎵 Playlist Operations

⭐ Ratings & Favorites

📊 Analytics & History

📻 Radio Management

*Note: Both create_radio_station and batch_create_radio_stations support an optional validateBeforeAdd parameter that will test stream URLs before adding them to Navidrome.

🎤 Lyrics & Timestamps

🏷️ Metadata & Tags

Troubleshooting

Common Issues

Connection Problems

• Verify that the Navidrome server is running.
• Check that the URL includes the protocol (http:// or https://).
• Ensure that the credentials are correct.
• Test with curl or a browser first.

macOS Specific

• See macOS Troubleshooting Guide
• Common issue: Node.js path not found
• Solution: Create symlinks or use full paths.

Configuration Issues

• Use absolute paths in config files.
• Validate JSON syntax (no trailing commas).
• Check that environment variables are set.
• Restart the client after changes.

Limitations

• Playback Control: This MCP server manages your library and queues but doesn't directly control playback. Use your Navidrome client app for play/pause/skip.
• Recently Played: Navidrome doesn't provide last - played timestamps, only play counts and completion status.
• Queue Management: Works with Subsonic - compatible clients that support jukebox mode.

Development

Setup for Contributors

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

# Development
pnpm dev       # Hot reload mode
pnpm test      # Run tests
pnpm lint      # Check code style
pnpm typecheck # Type checking

Testing with MCP Inspector

# Build first
pnpm build

# Web UI testing
npx @modelcontextprotocol/inspector node dist/index.js

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

Project Structure

navidrome-mcp/
├── src/           # TypeScript source
├── dist/          # Compiled JavaScript
├── docs/          # Documentation
├── tests/         # Test suites
└── CLAUDE.md      # AI assistant instructions

📄 License

Code: AGPL - 3.0

The source code is licensed under the GNU Affero General Public License v3.0. See LICENSE.

Documentation: CC - BY - SA - 4.0

The documentation is licensed under the Creative Commons Attribution - ShareAlike 4.0 International.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Built with ❤️ for the Navidrome community