getUsersSavedTracks
Retrieve a list of tracks from a user's "Liked Songs" library on Spotify, with options to limit results and paginate using offset.
Instructions
Get a list of tracks saved in the user's "Liked Songs" library
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of tracks to return (1-50) | |
| offset | No | Offset for pagination (0-based index) |
Input Schema (JSON Schema)
{
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"limit": {
"description": "Maximum number of tracks to return (1-50)",
"maximum": 50,
"minimum": 1,
"type": "number"
},
"offset": {
"description": "Offset for pagination (0-based index)",
"minimum": 0,
"type": "number"
}
},
"type": "object"
}
Implementation Reference
- src/read.ts:389-434 (handler)The main handler function that fetches the user's saved tracks from Spotify's 'Liked Songs' library using the Spotify API, applies pagination with limit and offset, formats the track information including artists, duration, ID, and added date, 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:376-388 (schema)Zod schema defining the input parameters for the tool: optional limit (1-50) and offset (0+) for paginating the list of saved tracks.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)The getUsersSavedTracks tool is registered by being included in the exported readTools array.export const readTools = [ searchSpotify, getNowPlaying, getMyPlaylists, getPlaylistTracks, getRecentlyPlayed, getUsersSavedTracks, getQueue, ];
- src/index.ts:12-14 (registration)Final registration of all tools, including those from readTools containing getUsersSavedTracks, to 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-14 (helper)Helper function used in the handler to type-guard and validate if an item is a SpotifyTrack.function isTrack(item: any): item is SpotifyTrack { return ( item && item.type === 'track' && Array.isArray(item.artists) && item.album && typeof item.album.name === 'string' ); }