getPlaylistTracks
Retrieve tracks from a Spotify playlist using its ID, with options for pagination and limiting results.
Instructions
Get a list of tracks in a Spotify playlist
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| playlistId | Yes | The Spotify ID of the playlist | |
| limit | No | Maximum number of tracks to return (1-50) | |
| offset | No | Offset for pagination (0-based index) |
Implementation Reference
- src/read.ts:272-319 (handler)The handler function that implements the core logic of the getPlaylistTracks tool. It takes playlistId, optional limit and offset, fetches the tracks using Spotify API via handleSpotifyRequest, validates tracks with isTrack, formats a numbered list with artist, duration, and ID, and returns a markdown-formatted text response with pagination info.
handler: async (args, _extra: SpotifyHandlerExtra) => { const { playlistId, limit = 50, offset = 0 } = args; const playlistTracks = await handleSpotifyRequest(async (spotifyApi) => { return await spotifyApi.playlists.getPlaylistItems( playlistId, undefined, undefined, limit as MaxInt<50>, offset, ); }); if ((playlistTracks.items?.length ?? 0) === 0) { return { content: [ { type: 'text', text: "This playlist doesn't have any tracks", }, ], }; } const formattedTracks = playlistTracks.items .map((item, i) => { const { track } = item; if (!track) return `${offset + i + 1}. [Removed track]`; if (isTrack(track)) { const artists = track.artists.map((a) => a.name).join(', '); const duration = formatDuration(track.duration_ms); return `${offset + i + 1}. "${track.name}" by ${artists} (${duration}) - ID: ${track.id}`; } return `${offset + i + 1}. Unknown item`; }) .join('\n'); return { content: [ { type: 'text', text: `# Tracks in Playlist (${offset + 1}-${offset + playlistTracks.items.length} of ${playlistTracks.total})\n\n${formattedTracks}`, }, ], }; }, - src/read.ts:258-271 (schema)Zod input schema defining parameters for the tool: playlistId (string, required), limit (number 1-50, optional), offset (number >=0, optional). Used for validation.
schema: { playlistId: z.string().describe('The Spotify ID of the playlist'), 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/index.ts:12-14 (registration)Final registration of the getPlaylistTracks tool with the MCP server. readTools (containing getPlaylistTracks) is spread into the array and each tool is registered via server.tool().
[...readTools, ...playTools, ...albumTools].forEach((tool) => { server.tool(tool.name, tool.description, tool.schema, tool.handler); }); - src/read.ts:603-612 (registration)getPlaylistTracks is included in the readTools array, which is exported from read.ts, imported into index.ts, and registered with the MCP server.
export const readTools = [ searchSpotify, getNowPlaying, getMyPlaylists, getPlaylistTracks, getRecentlyPlayed, getUsersSavedTracks, getQueue, getAvailableDevices, ]; - src/read.ts:6-14 (helper)Helper function used in the handler to validate if an item is a SpotifyTrack 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' ); }