qobuz-mcp
A local MCP server for exploring the Qobuz catalog and managing your Qobuz library (favorites and playlists); it does not control playback or download/stream audio.
Search the catalog: free-text search across albums, artists, tracks and playlists, with
limit/offsetpagination.Get details: album (full tracklist, artists and roles, awards, booklet links, UPC), track (performer, credits, composer, work, ISRC), playlist (entries include a
playlist_track_idneeded to remove or move duplicates), artist (optionally truncated biography + discography, filterable by release type), label (description + albums).Discover music: similar artists, similar albums, radios seeded from an album/artist/track, and track suggestions to extend a list.
Browse editorial content: genres (one tree level at a time), featured albums (new releases, press awards, best sellers, album of the week, editor picks, label selections), featured playlists by genre/tag, artist playlists, label sections, awards and their albums.
Read Qobuz magazine: search stories, or list stories about an album, artist, label, playlist or award (title, summary, authors, date, link — no full text).
Read your library: favorites (albums/artists/tracks with
favorited_at), owned or followed playlists, purchases, new releases from favorite artists/labels/awards, and whether given items are favorited or purchased.Change your library: add/remove favorites, create, update, delete and follow/unfollow playlists, add tracks, remove specific entries, and reorder entries by position.
Constraints: pages are capped at 100 items, some lists are fixed (up to 30 items, no paging), write tools are non‑idempotent and should require per-call confirmation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@qobuz-mcp add Random Access Memories to my Qobuz favorites"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
qobuz-mcp
A local MCP server for macOS that lets an AI assistant, such as Claude Desktop, Claude Code, Antigravity CLI or the Antigravity app, explore the Qobuz catalog and manage your Qobuz library: favorites and playlists.
Status: usable. Every step of the implementation plan is done, and the setup has been checked in Claude Desktop, Claude Code, Antigravity CLI and the Antigravity app. The server relies on an unofficial API: see the disclaimers below.
What it does
Search and browse the catalog: albums, artists, tracks, playlists, labels, genres.
Recommend music: similar albums, radios from an album, an artist or a track, suggestions to extend a list of tracks.
Browse editorial content: new releases, press awards, best sellers, album of the week, editorial playlists, awards, magazine stories.
Read your library: favorites, playlists you own or follow, purchases, new releases from your favorite artists, and whether given items are in your library.
Change your library: add or remove favorites, create, edit, reorder and delete playlists, follow or unfollow playlists.
It does not control playback, and it does not download or stream audio.
Related MCP server: qobuz-mcp
Disclaimers
This project is not affiliated with, endorsed or sponsored by Qobuz. "Qobuz" is a trademark of its owner, used here only to indicate compatibility.
It relies on Qobuz's unofficial web player API, outside Qobuz's terms of service. It may break at any time.
It is intended for strictly personal use of your own account.
It comes with no guarantee of any kind. You bear the risks of using it with your account.
Write tools rely on your MCP client asking you to confirm each call. If you allowlist them, or use an auto-approve mode, you remove the main safeguard against instructions hidden in third-party content, such as a playlist description asking the assistant to delete your playlists.
Prerequisites
macOS, since credentials are stored in the macOS Keychain.
Homebrew and uv:
brew install uv. uv installs the Python version the project needs.A Qobuz account.
Claude Desktop, Claude Code or Antigravity CLI (
brew install --cask antigravity-cli), or another MCP client that supports the stdio transport. The Gemini app cannot run a local server, and Gemini CLI no longer serves individual accounts.
Installation
git clone https://github.com/cheubes/qobuz-mcp.git
cd qobuz-mcp
scripts/install.shThe script installs the dependencies, runs the login described below when no credentials are stored, registers the server in Claude Code and Antigravity CLI when they are installed, and prints the block to add to the Claude Desktop configuration, with your paths. It skips the steps already done, except the Antigravity CLI registration, which it updates, so you can run it again. The sections below detail each step, to do them by hand.
Update
scripts/update.shThe script pulls the latest version and updates the dependencies. Then restart Claude Desktop and the Antigravity app, and open a new Claude Code or Antigravity CLI session. With --check, it also runs the live tests, which tell whether Qobuz changed its API: run it when a tool starts failing.
Login
uv run qobuz-mcp loginThe command opens the Qobuz sign-in page in your browser, and prints its URL in case the browser does not open. Sign in on Qobuz's own page: the command never sees your password. Qobuz then redirects the browser to a temporary local address, and the command stores a token in the macOS Keychain. The sign-in must complete within 5 minutes.
If the browser sign-in does not work, copy a token by hand from the Qobuz web player:
Open play.qobuz.com and sign in.
Open the browser's developer tools, on the Network tab, and reload the page.
Select any request to
www.qobuz.com/api.json/, and copy the value of itsX-User-Auth-Tokenrequest header.Run
uv run qobuz-mcp login --tokenand paste the token when prompted.
uv run qobuz-mcp logout removes the stored credentials. Login and logout apply to the next tool call, without restarting your MCP client.
The server identifies itself with the app_id of the Qobuz web player, read at login. If Qobuz rejects it, run login again. To force a value, set the QOBUZ_APP_ID environment variable in the server configuration.
Never share the token: it gives access to your Qobuz account.
Client configuration
Replace /path/to/qobuz-mcp with the absolute path of your clone.
Claude Code:
claude mcp add --scope user qobuz -- uv run --directory /path/to/qobuz-mcp qobuz-mcp serve--scope user makes the server available in every Claude Code session. Without it, the server is only registered for the directory where you ran the command.
Claude Desktop: add the server to ~/Library/Application Support/Claude/claude_desktop_config.json, then restart Claude Desktop. Claude Desktop does not inherit your shell PATH, so command must be the absolute path to uv, as printed by which uv (/opt/homebrew/bin/uv on Apple silicon, /usr/local/bin/uv on Intel Macs):
{
"mcpServers": {
"qobuz": {
"command": "/opt/homebrew/bin/uv",
"args": ["run", "--directory", "/path/to/qobuz-mcp", "qobuz-mcp", "serve"]
}
}
}Antigravity CLI and the Antigravity app:
agy mcp add qobuz -- /opt/homebrew/bin/uv run --directory /path/to/qobuz-mcp qobuz-mcp serveThe server goes to the global configuration, ~/.gemini/config/mcp_config.json, which the Antigravity desktop app also reads: it is available in every conversation of both. As for Claude Desktop, the app does not inherit your shell PATH, hence the absolute path to uv. scripts/install.sh runs this command at each install, which overwrites any change you made to the qobuz entry, such as an --env variable.
Whether Antigravity asks before running a tool depends on its agent mode, and Auto mode, the default, does not document how it treats MCP tools. Make every write tool ask for your approval: in an Antigravity CLI session, run /permissions and add an ask rule for each of them:
mcp(qobuz/add_favorites)
mcp(qobuz/remove_favorites)
mcp(qobuz/create_playlist)
mcp(qobuz/update_playlist)
mcp(qobuz/add_tracks_to_playlist)
mcp(qobuz/remove_tracks_from_playlist)
mcp(qobuz/move_playlist_tracks)
mcp(qobuz/delete_playlist)
mcp(qobuz/follow_playlist)
mcp(qobuz/unfollow_playlist)The rules are global: they apply to the CLI and to the app. To stop confirming a read-only tool, add an allow rule for that tool only, such as mcp(qobuz/search_catalog), never for the whole server. Never use --dangerously-skip-permissions or the always-proceed tool permission with this server: they bypass these rules and remove the confirmation of write tools.
In the other clients, read-only tools can be allowed once. Keep the confirmation of write tools: see the last disclaimer above.
How it is built
The project is specification-driven. Everything starts in specs/:
Functional specifications: scope, tools, behaviors and acceptance criteria.
Technical specifications: stack, architecture, API usage, tests, CI.
Architecture decision records: why things are the way they are, and which alternatives were rejected.
Implementation plan: build order and progress. CI checks that every acceptance criterion of a completed step is covered by a test.
Development is assisted by Claude Code, following the project rules in CLAUDE.md.
Contributing and security
Contributions start with an issue: see CONTRIBUTING.md. To report a vulnerability, see SECURITY.md.
License
CC0 1.0 Universal: the code is dedicated to the public domain.
Available Tools
34 toolsadd_favoritesAdd FavoritesB
Add albums, artists and/or tracks to the user's favorites, in one call.
Inputs: album_ids, track_ids, artist_ids. Returns: status
add_tracks_to_playlistAdd Tracks To PlaylistA
Append tracks at the end of a playlist the user owns, in the given order.
Inputs: track_ids (required), playlist_id (required). Returns: id, url, name, owner, +6 more
check_libraryCheck LibraryARead-only
Check whether given albums, artists and tracks are in the user's favorites, and whether given albums and tracks are purchased.
Results keep the order of the given IDs. purchased is null for artists.
Inputs: album_ids, track_ids, artist_ids. Returns: albums, tracks, artists
create_playlistCreate PlaylistA
Create a playlist owned by the user, private and non-collaborative unless requested.
Returns the new playlist with its ID, to add tracks with add_tracks_to_playlist.
Inputs: name (required), is_public, description, is_collaborative. Returns: id, url, name, owner, +6 more
delete_playlistDelete PlaylistADestructive
Delete a playlist the user owns. This cannot be undone.
To stop following someone else's playlist, use unfollow_playlist instead.
Inputs: playlist_id (required). Returns: status
follow_playlistFollow PlaylistA
Follow a playlist, such as an editorial or another user's playlist.
Followed playlists appear in list_my_playlists.
Inputs: playlist_id (required). Returns: status
get_albumGet AlbumARead-only
Get an album's details: tracklist, audio quality, artists and roles, label, genre, release date, description, press awards and booklet links.
The tracklist is paginated with limit and offset; tracks.has_more tells whether more
tracks exist.
Inputs: album_id (required), limit, offset. Returns: id, upc, url, genre, +18 more
get_artistGet ArtistARead-only
Get an artist's biography and discography, newest releases first.
By default, biography is the start of the biography, at most 1,000 characters cut at a
sentence end, and biography_truncated tells whether text was cut. Set full_biography
when the user wants to know more about the artist: the full text can reach several
thousand characters. The discography is paginated with limit and offset;
albums.has_more tells whether more releases exist. Use get_similar_artists to discover
related artists.
Inputs: artist_id (required), limit, offset, release_type, +1 more. Returns: id, url, name, albums, +3 more
get_awardGet AwardARead-only
Get a press award and the albums that received it, optionally for one genre.
The albums are paginated with limit and offset; albums.has_more tells whether more
albums exist.
Inputs: award_id (required), limit, offset, genre_id. Returns: id, url, name, albums
get_labelGet LabelARead-only
Get a record label's description and its albums.
The albums are paginated with limit and offset; albums.has_more tells whether more
albums exist.
Inputs: label_id (required), limit, offset. Returns: id, url, name, albums, +1 more
get_playlistGet PlaylistARead-only
Get a playlist's details and its entries, paginated with limit and offset.
Each entry has a playlist_track_id, which identifies that entry in the playlist (the same
track can appear twice), and the track itself with its id. Removing or moving entries
takes playlist_track_id values.
Inputs: playlist_id (required), limit, offset. Returns: id, url, name, owner, +8 more
get_radioGet RadioARead-only
Get the tracks of a radio built by Qobuz from an album, an artist or a track.
Qobuz returns one fixed list of up to 30 tracks, with no further pages. Use
suggest_tracks instead to continue a list of tracks, such as a playlist.
Inputs: seed_id (required), seed_type (required). Returns: items, limit, total, offset, +1 more
get_similar_artistsGet Similar ArtistsARead-only
List artists similar to a given artist, as Qobuz suggests them, to discover new music.
Inputs: artist_id (required), limit, offset. Returns: items, limit, total, offset, +1 more
get_trackGet TrackBRead-only
Get a track's details: main performer, credits, composer, work, album, audio quality, ISRC and release date.
credits is Qobuz's own text listing every contributor with their roles.
Inputs: track_id (required). Returns: id, url, isrc, work, +14 more
list_artist_playlistsList Artist PlaylistsARead-only
List Qobuz's editorial playlists featuring an artist.
Use get_playlist to see a playlist's tracks.
Inputs: artist_id (required), limit, offset. Returns: items, limit, total, offset, +1 more
list_awardsList AwardsARead-only
List press awards and distinctions, with the publication that grants them.
Use get_award for an award's albums, and list_related_stories for its stories.
Inputs: limit, offset. Returns: items, limit, total, offset, +1 more
list_favoritesList FavoritesARead-only
List the user's favorite albums, artists or tracks, newest first.
Each item comes with favorited_at, the date it was added to the favorites.
Inputs: type (required), limit, offset. Returns: result
list_featured_albumsList Featured AlbumsARead-only
List albums from one of Qobuz's editorial selections, optionally for one genre.
Inputs: category (required), limit, offset, genre_id. Returns: items, limit, total, offset, +1 more
list_featured_playlistsList Featured PlaylistsARead-only
List Qobuz's editorial playlists, optionally for one genre or one tag.
Use get_playlist to see a playlist's tracks.
Inputs: tag, limit, offset, genre_id. Returns: items, limit, total, offset, +1 more
list_genresList GenresARead-only
List Qobuz genres, one level of the tree at a time.
Each genre's path holds its ancestor genre IDs, from the root to its direct parent.
Genre IDs filter list_featured_albums and list_featured_playlists.
Inputs: limit, offset, parent_genre_id. Returns: items, limit, total, offset, +1 more
list_label_itemsList Label ItemsARead-only
List one section of a record label: artists, albums or playlists, matching section.
Use get_label for the label's description and its whole catalog of albums.
Inputs: section (required), label_id (required), limit, offset. Returns: result
list_my_playlistsList My PlaylistsARead-only
List the playlists the user owns or follows.
Only playlists the user owns can be changed by the write tools.
Inputs: limit, filter, offset. Returns: items, limit, total, offset, +1 more
list_new_releases_from_favoritesList New Releases From FavoritesCRead-only
List recent releases from the user's favorite artists, labels or awards.
Inputs: source (required), limit, offset, genre_id. Returns: items, limit, total, offset, +1 more
list_purchasesList PurchasesARead-only
List the albums or tracks the user has purchased on Qobuz.
Inputs: type (required), limit, offset. Returns: result
list_similar_albumsList Similar AlbumsARead-only
List albums similar to a given album, as Qobuz recommends them.
Qobuz returns one fixed list of up to 30 albums, with no further pages.
Inputs: album_id (required). Returns: items, limit, total, offset, +1 more
move_playlist_tracksMove Playlist TracksADestructive
Reorder entries within a playlist the user owns.
The entries, identified by playlist_track_id, are moved in front of the entry currently
at position insert_before (positions as returned by get_playlist, starting at 1).
Inputs: playlist_id (required), insert_before (required), playlist_track_ids (required). Returns: id, url, name, owner, +6 more
remove_favoritesRemove FavoritesBDestructive
Remove albums, artists and/or tracks from the user's favorites, in one call.
Inputs: album_ids, track_ids, artist_ids. Returns: status
remove_tracks_from_playlistRemove Tracks From PlaylistADestructive
Remove entries from a playlist the user owns.
Entries are identified by playlist_track_id, so only the targeted occurrence of a track
that appears several times is removed.
Inputs: playlist_id (required), playlist_track_ids (required). Returns: id, url, name, owner, +6 more
search_catalogSearch CatalogARead-only
Search the Qobuz catalog for albums, artists, tracks or playlists.
Returns one page of items of the requested type, with their Qobuz IDs and public URLs.
Use the IDs with the other tools, for example get_album for an album.
Inputs: type (required), query (required), limit, offset. Returns: result
search_storiesSearch StoriesARead-only
Search Qobuz magazine stories: news, interviews, reviews.
Each story comes with its title, summary, authors, date and sections, and a link to read it on Qobuz. The full text is not available.
Inputs: query (required), limit, offset. Returns: items, limit, total, offset, +1 more
suggest_tracksSuggest TracksARead-only
Suggest tracks to continue a list of tracks, for example to extend a playlist.
The given tracks are never suggested. The result is one complete page of up to limit
tracks, with no further pages.
Inputs: track_ids (required), limit. Returns: items, limit, total, offset, +1 more
unfollow_playlistUnfollow PlaylistADestructive
Stop following a playlist. The playlist itself is not deleted.
Inputs: playlist_id (required). Returns: status
update_playlistUpdate PlaylistADestructive
Change a playlist's name, description, visibility or collaborative flag.
Only the fields given are changed; the others keep their current value.
Inputs: playlist_id (required), name, is_public, description, +1 more. Returns: id, url, name, owner, +6 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 34 tools
Each tool has a distinct resource+action target, and descriptions actively disambiguate the tricky pairs (delete_playlist vs unfollow_playlist, list_label_items vs get_label, get_radio vs suggest_tracks, add/remove favorites vs favorites listing). A few boundaries are still soft: search_stories vs list_related_stories, list_favorites vs check_library vs list_purchases, and list_featured_playlists vs list_artist_playlists vs list_my_playlists all live near each other, but the descriptions make the intended usage recoverable.
The surface is almost entirely consistent snake_case verb_noun (get_*, list_*, add_*, remove_*, create_playlist, update_playlist). Minor deviations: the same 'related items' concept is named get_similar_artists but list_similar_albums, and list_my_playlists uses a possessive that no other tool uses.
34 tools is heavy for a music service and pushes past the comfortable range, even though the domain genuinely spans catalog, editorial, magazine, awards and user library. Each tool does map to a real endpoint, so it is over-scoped rather than padded, but an agent faces a large selection surface.
Coverage is strong: catalog search/browse, artist/album/track/label detail, genres, editorial, awards, stories, favorites, purchases, library checks, and full playlist CRUD plus track add/remove/reorder/follow. Minor gaps remain (no user profile/subscription info, no lyrics or audio-stream/preview handles, no artist top-tracks view outside the discography).
Maintenance
Related MCP Connectors
Music industry tools for AI agents: artist research, catalogs, release plans and content.
Search, analyze, and discover commercially released music using sonic intelligence.
manage your music catalog through conversation — works, recordings, credits, agreements, royalties
Create songs from prompts or lyrics, check credits, and access your private library with OAuth.
Related MCP Servers
- FlicenseBqualityDmaintenanceEnables AI assistants to control Spotify playback, search for music, manage playlists, and interact with your Spotify library through natural language commands.19-
- AlicenseNot gradedqualityDmaintenanceConnects your Qobuz account to Claude for music search, playlist management, favorites browsing, and streaming URL retrieval through natural conversation.MIT
- AlicenseAqualityBmaintenanceEnables AI assistants to access TIDAL Music catalog, including search, playlists, favorites, and recommendations.14MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to control Spotify playback, search music, manage playlists and library, and access user listening insights via the Spotify Web API.-