Spotify MCP Server

Instructions

Implementation Reference

• src/read.ts:384-450 (handler)

  Complete definition of the getUsersSavedTracks tool including name, schema for limit and offset parameters, and the handler function that retrieves the user's saved tracks ("Liked Songs") from the Spotify API, formats the track list with artist names, duration, ID, and added date, handles pagination and empty results, and returns a formatted markdown text response.

  const getUsersSavedTracks: tool<{
    limit: z.ZodOptional<z.ZodNumber>;
    offset: z.ZodOptional<z.ZodNumber>;
  }> = {
    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)'),
    },
    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:603-612 (registration)

  The getUsersSavedTracks tool is registered by being included in the exported readTools array, likely used elsewhere to register all read-related MCP tools.

  export const readTools = [
    searchSpotify,
    getNowPlaying,
    getMyPlaylists,
    getPlaylistTracks,
    getRecentlyPlayed,
    getUsersSavedTracks,
    getQueue,
    getAvailableDevices,
  ];

• src/read.ts:391-403 (schema)

  Zod-based input schema for the tool, defining optional 'limit' (1-50) and 'offset' (min 0) parameters with descriptions.

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