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'
  );

Spotify MCP Server