Navidrome

Transform your Navidrome music server with an AI-powered assistant. This MCP server lets Claude, ChatGPT, and other MCP-compatible clients interact with your library through natural language, enabling intelligent playlist creation, music discovery, and library management.

How to use

You connect an MCP client to Navidrome MCP to start asking questions about your library, request playlists, get music recommendations, and manage your collection via natural language. Use the client to browse and search your library, create and reorder playlists, validate radio streams, and discover new music based on Last.fm and Radio Browser data. You can also access time-synced lyrics and detailed metadata to inform your conversations with your AI assistant.

How to install

Prerequisites: you need Node.js 20+ and a running Navidrome server with your music library. Install a compatible MCP client such as Claude Desktop or ChatGPT Desktop.

Step 1. Quick setup using the npm package (recommended) Open your terminal and run:npm install -g navidrome-mcp

Step 2. Create a configuration for Claude/ChatGPT Desktop by adding an MCP server entry as shown in the configuration example below. Use your actual server URL and credentials where indicated.

Step 3. Start the MCP server. If you installed the package globally, launching the MCP server via the client will auto-start the MCP integration on first use.

Configuration and start options

Two explicit startup options are provided for Navidrome MCP. Use the npm-based method for automatic updates, or choose the manual build method if you prefer a local, self-contained start.

npm-based start (recommended): The MCP server runs with npx navidrome-mcp and uses your configured environment to connect to Navidrome.

manual build (alternative): Build the project, then run the distributed index.js with node and provide Navidrome/MCP related environment variables.

Notes and tips

Set NAVIDROME_DEFAULT_LIBRARIES to choose which Navidrome libraries are active by default (e.g., "1,2,3"). If not set, all libraries are active.

Get a free Last.fm API key to enable music discovery features. Radio Browser integration requires a User-Agent string.

Lyrics are available via LRCLIB without API keys. Restart the desktop client after saving configuration.

Powerful usage ideas

Ask your AI assistant to analyze listening history, identify missing albums by top artists, or build mood-based playlists from your owned tracks.

Troubleshooting

If you encounter connection issues, ensure the Navidrome server is reachable at the configured URL and that credentials are correct. Restart the MCP client after changes.

Development and testing

If you contribute, you can build and test MCP features locally. Use the Inspector tool to validate tools and simulate API calls.

License and support

Code is licensed under AGPL-3.0. Documentation is CC-BY-SA-4.0. For issues or discussions, use the project’s official channels.

Available tools

test_connection

Verify Navidrome server connectivity and feature status

get_song

Detailed song information

get_album

Detailed album information

get_artist

Detailed artist information

get_song_playlists

Get all playlists that contain a specific song

get_user_details

Get user information and available libraries

set_active_libraries

Set which libraries are active for filtering content

search_all

Search across all content types

search_songs

Search for specific songs

search_albums

Search for albums

search_artists

Search for artists

get_similar_artists

Find similar artists (Last.fm)

get_similar_tracks

Find similar tracks (Last.fm)

get_artist_info

Artist biography and tags

get_top_tracks_by_artist

Get top tracks for an artist from Last.fm

get_trending_music

Global music trends

list_playlists

View all playlists

get_playlist

Get detailed information about a specific playlist by ID

create_playlist

Create new playlist

update_playlist

Update playlist metadata

delete_playlist

Remove playlist

get_playlist_tracks

Get playlist contents

add_tracks_to_playlist

Add multiple types of content to a playlist

remove_tracks_from_playlist

Remove specific tracks from a playlist

reorder_playlist_track

Reorder track in a playlist

star_item

Mark item as favorite

unstar_item

Remove item from favorites

set_rating

Set 0-5 star rating for an item

list_starred_items

View favorites

list_top_rated

View highest rated items

list_recently_played

View recent listening activity

list_most_played

Find most played content

get_queue

View playback queue

set_queue

Set playback queue

clear_queue

Clear the playback queue

validate_radio_stream

Test radio stream URL validity

list_radio_stations

View all stations

get_radio_station

Get details about a radio station by ID

create_radio_station

Create radio stations (JSON array format)

delete_radio_station

Delete a radio station by ID

play_radio_station

Start radio playback

get_current_radio_info

Get info about the currently playing radio station

discover_radio_stations

Find internet radio stations globally

get_radio_filters

Get available search filters for radio stations

get_station_by_uuid

Get detailed station information by UUID

click_station

Register a play click for popularity metrics

vote_station

Vote for a radio station

get_lyrics

Get synchronized and plain text lyrics

search_by_tags

Search by specific tags

get_tag_distribution

Analyze tag usage patterns and distribution

get_filter_options

Get available filter values for search operations