getUsersSavedTracks
Retrieve tracks saved in your Spotify Liked Songs library with pagination controls for managing large collections.
Instructions
Get a list of tracks saved in the user's "Liked Songs" library
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of tracks to return (1-50) | |
| offset | No | Offset for pagination (0-based index) |
Implementation Reference
- src/read.ts:389-434 (handler)The core handler function that executes the tool logic: fetches user's saved tracks ("Liked Songs") via Spotify API with pagination (limit/offset), handles empty results, formats track details (name, artists, duration, ID, added date) using helpers like isTrack and formatDuration, and returns a formatted text response.
handler: async (args, _extra: SpotifyHandlerExtra) => { const { limit = 50, offset = 0 } = args; const savedTracks = await handleSpotifyRequest(async (spotifyApi) => { return await spotifyApi.currentUser.tracks.savedTracks( limit as MaxInt<50>, offset, ); }); if (savedTracks.items.length === 0) { return { content: [ { type: 'text', text: "You don't have any saved tracks in your Liked Songs", }, ], }; } const formattedTracks = savedTracks.items .map((item, i) => { const track = item.track; if (!track) return `${i + 1}. [Removed track]`; if (isTrack(track)) { const artists = track.artists.map((a) => a.name).join(', '); const duration = formatDuration(track.duration_ms); const addedDate = new Date(item.added_at).toLocaleDateString(); return `${offset + i + 1}. "${track.name}" by ${artists} (${duration}) - ID: ${track.id} - Added: ${addedDate}`; } return `${i + 1}. Unknown item`; }) .join('\n'); return { content: [ { type: 'text', text: `# Your Liked Songs (${offset + 1}-${offset + savedTracks.items.length} of ${savedTracks.total})\n\n${formattedTracks}`, }, ], }; }, - src/read.ts:373-388 (schema)Input schema definition using Zod for validation: optional limit (1-50) and offset (>=0). Includes tool name and description.
name: 'getUsersSavedTracks', description: 'Get a list of tracks saved in the user\'s "Liked Songs" library', schema: { limit: z .number() .min(1) .max(50) .optional() .describe('Maximum number of tracks to return (1-50)'), offset: z .number() .min(0) .optional() .describe('Offset for pagination (0-based index)'), }, - src/read.ts:531-539 (registration)Local registration: getUsersSavedTracks is added to the readTools array alongside other read-related tools for collective export.
export const readTools = [ searchSpotify, getNowPlaying, getMyPlaylists, getPlaylistTracks, getRecentlyPlayed, getUsersSavedTracks, getQueue, ]; - src/index.ts:12-14 (registration)Global registration: All tools from readTools (including getUsersSavedTracks) are looped over and registered with the MCP server using server.tool().
[...readTools, ...playTools, ...albumTools].forEach((tool) => { server.tool(tool.name, tool.description, tool.schema, tool.handler); }); - src/read.ts:6-13 (helper)Supporting helper function used in the handler to type-guard and validate Spotify track items before formatting.
function isTrack(item: any): item is SpotifyTrack { return ( item && item.type === 'track' && Array.isArray(item.artists) && item.album && typeof item.album.name === 'string' );