get_playlist_items
Retrieve detailed information about tracks and episodes in a Spotify playlist, including metadata and playback options, using the playlist's ID or URI.
Instructions
Get full details of the items of a playlist
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The Spotify ID or URI of the playlist | |
| market | No | Optional. An ISO 3166-1 alpha-2 country code | |
| fields | No | Optional. Filters for the query | |
| limit | No | Optional. Maximum number of items to return (1-100) | |
| offset | No | Optional. Index of the first item to return |
Implementation Reference
- src/handlers/playlists.ts:38-52 (handler)The core handler function implementing the get_playlist_items tool. It extracts the playlist ID, builds query parameters (market, limit, offset, fields), and makes a GET request to Spotify's /playlists/{id}/items endpoint via the SpotifyApi utility.
async getPlaylistItems(args: PlaylistItemsArgs) { const playlistId = this.extractPlaylistId(args.id); const { market, limit, offset, fields } = args; const params = { market, ...(limit !== undefined && { limit }), ...(offset !== undefined && { offset }), ...(fields !== undefined && { fields }) }; return this.api.makeRequest( `/playlists/${playlistId}/items${this.api.buildQueryString(params)}` ); } - src/types/playlists.ts:12-15 (schema)TypeScript interface defining the input arguments for the getPlaylistItems handler: playlist ID (required), fields (optional), extending MarketParams (market) and PaginationParams (limit, offset). Used for type safety and validation.
export interface PlaylistItemsArgs extends MarketParams, PaginationParams { id: string; fields?: string; } - src/index.ts:495-526 (registration)MCP tool registration in listTools response: defines name, description, and inputSchema matching the handler arguments.
name: 'get_playlist_items', description: 'Get full details of the items of a playlist', inputSchema: { type: 'object', properties: { id: { type: 'string', description: 'The Spotify ID or URI of the playlist' }, market: { type: 'string', description: 'Optional. An ISO 3166-1 alpha-2 country code' }, fields: { type: 'string', description: 'Optional. Filters for the query' }, limit: { type: 'number', description: 'Optional. Maximum number of items to return (1-100)', minimum: 1, maximum: 100 }, offset: { type: 'number', description: 'Optional. Index of the first item to return', minimum: 0 } }, required: ['id'] }, }, - src/index.ts:845-851 (registration)Dispatch handler in the main CallToolRequest switch statement: validates arguments, calls the playlistsHandler.getPlaylistItems, and returns JSON stringified result.
case 'get_playlist_items': { const args = this.validateArgs<PlaylistItemsArgs>(request.params.arguments, ['id']); const result = await this.playlistsHandler.getPlaylistItems(args); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], }; } - src/handlers/playlists.ts:8-10 (helper)Helper method used by getPlaylistItems (and other playlist methods) to normalize playlist ID from Spotify URI or plain ID.
private extractPlaylistId(id: string): string { return id.startsWith('spotify:playlist:') ? id.split(':')[2] : id; }