Skip to main content
Glama
qobuz-mcp
by cheubes

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.sh

The 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.sh

The 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 login

The 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:

  1. Open play.qobuz.com and sign in.

  2. Open the browser's developer tools, on the Network tab, and reload the page.

  3. Select any request to www.qobuz.com/api.json/, and copy the value of its X-User-Auth-Token request header.

  4. Run uv run qobuz-mcp login --token and 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 serve

The 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/:

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 tools
add_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 LibraryA
Read-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 PlaylistA
Destructive

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 AlbumA
Read-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 ArtistA
Read-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 AwardA
Read-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 LabelA
Read-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 PlaylistA
Read-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 RadioA
Read-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 ArtistsA
Read-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 TrackB
Read-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 PlaylistsA
Read-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 AwardsA
Read-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 FavoritesA
Read-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_genresList GenresA
Read-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 ItemsA
Read-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 PlaylistsA
Read-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 FavoritesC
Read-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 PurchasesA
Read-only

List the albums or tracks the user has purchased on Qobuz.

Inputs: type (required), limit, offset. Returns: result

list_similar_albumsList Similar AlbumsA
Read-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 TracksA
Destructive

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 FavoritesB
Destructive

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 PlaylistA
Destructive

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 CatalogA
Read-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 StoriesA
Read-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 TracksA
Read-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 PlaylistA
Destructive

Stop following a playlist. The playlist itself is not deleted.

Inputs: playlist_id (required). Returns: status

update_playlistUpdate PlaylistA
Destructive

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

    A3.5/5.0

    Scored across 34 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers