Synthseek ships an MCP server. Connect an assistant such as Claude, and you can manage your library by asking, in plain language, the way you would ask a person who looks after your music.
Every connection belongs to one member. The assistant sees and acts on that member’s account and library only, with access shaped by their role. Secret values are never returned, whatever is asked.
Connecting
What you need
A publicly reachable HTTPS address for your instance, set as PUBLIC_BASE_URL. Assistants that run in the cloud call back over the internet, so a local address will not work for them.
Either an API key created in Settings, then Apps & API keys, or the OAuth flow, which most clients will use automatically.
The endpoint
plaintext
POST https://your-instance/api/v1/mcp
It speaks Streamable HTTP and accepts either a Bearer API key or an OAuth 2.1 access token. Synthseek runs its own OAuth authorisation server with a consent screen, so a client that supports discovery needs nothing but the URL.
Example, Claude Code
bash
claude mcp add --transport http synthseek https://your-instance/api/v1/mcp --scope user
Then run /mcp and complete the authorisation in your browser.
What you can ask for
“Build me a playlist of upbeat 2000s pop punk.” The assistant finds the songs, downloads whatever you are missing, and saves the playlist.
“Get me the latest album from that artist.” It looks it up and downloads the whole album.
“Recommend some new music based on what I have been listening to, and grab a few tracks.” It reads your listening history, suggests songs, and adds them.
“What is stuck in my downloads?” It reads the download queue, and can explain why something failed.
“Shuffle my Daft Punk songs, and play this one next.” It plays them on your open player and edits its queue.
A weekly routine. Have the assistant rebuild personal mixes each week from your recent listening, refreshing the same playlists rather than piling up duplicates, and downloading anything you do not have.
The tools
Search and discovery
Tool
What it does
search_music
Find songs, albums, artists, and playlists to download. Understands moods and genres.
get_music_details
Full details of one specific item.
get_artist_overview
An artist’s profile, albums, top tracks, and similar artists in one call.
get_artist_discography
Everything an artist released, and which of it you are still missing.
get_trending
What is trending right now, from real charts.
browse_genres
The genres available to explore.
get_recommendations
Personalised picks from your connected ListenBrainz or Last.fm.
resolve_url
Turn a link from another platform into requestable songs.
Downloads
Tool
What it does
download_track
Download one song.
download_album
Download a full album.
download_playlist
Download an entire catalog playlist.
retry_all_failed
Retry every failed download at once.
Requests
Tool
What it does
list_requests
Your requests and how far along they are, including ones waiting for approval.
get_request
One download in detail, per track, with where each song came from and any failures.
control_request
Prioritise, pause, resume, cancel, or retry a song, album, or playlist download.
upgrade_tracks
Look for a better quality copy of songs you already have.
get_my_quota
How much of your download allowance you have used.
decide_request
Approve or turn down a member’s request. Administrators only.
Playlists
Tool
What it does
list_playlists
Your playlists, with track counts and where each one is synced.
get_playlist
One playlist in detail.
create_playlist
Create one from tracks already in your library.
add_tracks_to_playlist
Add tracks.
replace_playlist_tracks
Set the complete track list, replacing what was there.
remove_tracks_from_playlist
Remove tracks.
delete_playlist
Delete a playlist.
update_playlist
Rename, or toggle keep-in-sync.
sync_playlist_to_media_server
Push one playlist, or all eligible ones, to Plex, Navidrome, or Jellyfin.
Library
Tool
What it does
get_library_summary
Totals, top artists and genres, and queue size.
search_library
Search what you already have.
set_favorite
Mark songs, albums, or artists as favourites, or unmark them.
list_favorites
Your favourite songs, albums, and artists.
Listening history
Tool
What it does
get_listening_history
What you played recently and your most played songs and artists, no Last.fm account needed.
get_lastfm_scrobbles
Your top tracks, recent tracks, or top artists from Last.fm, over any period.
Player
Tool
What it does
get_play_queue
What is playing and what comes next.
edit_play_queue
Add songs to the queue, next or at the end, remove or move them, or clear it.
play
Play songs, an album, an artist, or a playlist now, in order or shuffled.
now_playing
What is playing right now, and on which of your open players.
control_player
Play, pause, skip, seek, volume, shuffle, repeat, mute, or move playback to another player.
start_radio
Play similar songs from your library, starting from a song or an artist.
get_lyrics
The words of a song.
get_player_settings
How a player is set up: equalizer, compressor, transitions, conversion, and what it shows.
set_player_settings
Change those, plus volume normalisation and autoplay.
set_player_view
Show or hide the lyrics, the full-screen player, or the queue, or resize the bar.
The player tools act on a Synthseek page open in a browser. With none open, play and edit_play_queue save the queue for the next player you open.
Settings
Tool
What it does
get_settings
View the settings you are allowed to see. Secrets are always hidden.
update_setting
Change a settings section you are allowed to manage.
System and operations
Administrators only.
Tool
What it does
get_download_queue_stats
The download queue at a glance, including whether it is paused.
pause_download_queue
Pause downloading and everything in progress.
resume_download_queue
Resume downloading.
trigger_job
Start a background job now. It returns once the job is running.
list_jobs
List the background jobs and which are doing work right now.
get_system_health
Check Synthseek and its connected services.
get_maintenance_status
Everything that needs your attention, in one summary.
review_imports
Look at downloads held back for a check, then keep or discard them.
check_for_updates
Whether a newer Synthseek version is out.
list_log_files
The available log files.
read_logs
Recent log entries, for troubleshooting.
Two things worth knowing
retry_all_failed is track-level. It re-queues every failed track, including tracks under albums and playlists that themselves show as complete or partially complete. A container being complete does not mean it has no failed tracks.
Search results are not playlist-ready.search_music returns catalog identifiers. The playlist and player tools take Synthseek’s own track identifiers, which come from download_track and search_library. Assistants handle this themselves; it matters only if you are building against the tools directly.