MCP tool reference

Documentation Index

Fetch the complete documentation index at: https://clickwheel.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

The clickwheel MCP server exposes these tools to Claude and other MCP clients. See MCP server for setup. Each tool wraps the same core logic as the CLI. 37 tools across 6 domains.

​

Apple Music

​

apple_music_health

Probe the Apple Music integration end-to-end without changing anything.

​

delete_apple_music_playlist

Delete a library playlist from the user’s Apple Music account.

​

list_apple_music_playlists

List every library playlist in the user’s Apple Music account.

​

pull_playlist_from_apple_music

Import a library playlist from Apple Music into clickwheel.

​

sync_playlist_to_apple_music

Create a playlist in the user’s Apple Music account from a clickwheel playlist.

​

Last.fm

​

get_pending_scrobbles

Cached iPod plays that haven’t yet been submitted to Last.fm. Each entry has artist, title, album, timestamp (unix seconds), and duration_seconds.

​

submit_scrobbles

Pull recent plays from the iPod and submit them to Last.fm.

​

Library

​

library_health

Setup probe: does the library directory exist, when was the last scan, how many indexed tracks are now missing from disk, is auto-scan enabled, etc.

​

library_stats

High-level stats for the indexed music library.

​

list_albums_by_artist

Albums for a single artist, ordered by year then album title. Each entry includes track count, total size in bytes, and the year (if known).

​

list_artists

All artists in the indexed library, alphabetical, with track count, album count, and total size in bytes per artist. FLAC tracks are excluded (the iPod doesn’t play FLAC).

​

list_tracks_by_album

All tracks on one album, ordered by disc/track number. Returns full track records: title, path, duration, file size, format, year, etc.

​

search_tracks

Case-insensitive substring search across artist, album, and title.

​

Playlists

​

add_artist_to_playlist

Add every track by artist to playlist (skipping duplicates). Creates the playlist if it doesn’t already exist. Returns the number of tracks actually added.

​

create_playlist

Create a new named playlist (a curated collection — workout mix, road trip, etc.) with the given track paths. Errors if a playlist with the same name already exists — use update_playlist to replace contents instead.

​

delete_playlist

Permanently delete a saved playlist. Cannot be undone — the playlist record is removed; the underlying music files are untouched.

​

get_playlist

Summary of one playlist: total track count, total size, and the artist breakdown (with track count + size per artist). Does NOT return the full track list — use list_playlist_tracks to page through tracks.

​

heal_playlist

Drop references in a playlist to tracks whose files are no longer on disk (flagged missing by clickwheel scan). Returns the number dropped, the number remaining, and the list of removed track records.

​

list_playlist_tracks

Paginated list of tracks in a saved playlist, in playlist order. Returns full track records (artist, title, album, path, duration, file_size, format) — the path values are needed if you’re going to pass them to update_playlist.

​

list_playlists

All saved playlists (the curated, named collections — workout mix, road trip, etc.) with track counts, total size in bytes, and last-updated timestamps.

​

remove_artist_from_playlist

Remove every track by artist from playlist. Returns the number of tracks removed (0 if the artist wasn’t in the playlist).

​

set_playlist_description

Set a saved playlist’s description without touching its track list.

​

update_playlist

Replace a playlist’s contents wholesale (or create it if it doesn’t exist). Returns the new track count and replaced (True if a playlist by this name already existed).

​

Plex

​

list_plex_playlists

List every audio playlist on the user’s Plex server.

​

plex_health

Probe the Plex integration end-to-end without changing anything.

​

pull_playlist_from_plex

Recover a Plex audio playlist into clickwheel’s local SQLite.

​

sync_playlist_to_plex

Push a clickwheel playlist into the user’s Plex music library so it shows up in Plex web and Plexamp alongside the iPod sync.

​

iPod

​

add_artist_to_ipod

Push every track by an artist to the iPod’s library, no playlist artifact. Convenience wrapper over add_tracks_to_ipod that resolves the artist’s tracks via the library index.

​

add_tracks_to_ipod

Push specific tracks to the iPod’s library WITHOUT creating a playlist on the device. Tracks land in the main library and are browsable by artist/album.

​

eject_ipod

Safely unmount the iPod via diskutil eject. Idempotent: if no iPod is currently mounted, returns {"ejected": False, "already_unmounted": True} rather than raising. This handles the classic iPod’s normal post-sync auto-disconnect — after the device finishes writing its iTunesDB, its firmware flips the screen back to the menu and tells macOS it’s safe to remove, at which point the volume dismounts automatically. So by the time the user asks you to eject, the iPod may already be gone. That’s expected; tell the user the iPod auto-disconnected and they’re safe to unplug. Other things that can cause an idle disconnect: macOS Music.app auto-eject after activity, USB selective-suspend on battery, the iPod’s own drive-spindown power-saving.

​

get_ipod_contents

High-level snapshot of what’s on the iPod: capacity, used/free space, track/artist/album counts, and the top 25 artists by track count. Does NOT return the full track list — use list_ipod_tracks to page through tracks (optionally filtered by artist).

​

list_ipod_playlists

List the playlists currently on the iPod (the ones visible under Music → Playlists on the device).

​

list_ipod_tracks

Paginated list of tracks on the iPod, optionally filtered by artist. Each track is the chat-friendly slice — artist, title, album, size in bytes. For the full per-track payload, use the CLI.

​

remove_artist_from_ipod

Drop every track by an artist from the iPod, in one shot.

​

remove_ipod_playlist

Remove a playlist from the iPod (Music → Playlists). The playlist’s tracks are NOT deleted — they stay in the iPod’s main library, browsable by artist/album. Only the playlist artifact goes away.

​

remove_tracks_from_ipod

Remove specific tracks from the iPod — drops them from the iTunesDB AND deletes the underlying audio files from the device.

​

sync_playlist_to_ipod

Push a saved playlist (the clickwheel-side draft) to the iPod AND create/update the corresponding playlist on the device under Music → Playlists. Copies any missing tracks first.