MCP Spotify Server

Instructions

Implementation Reference

• src/handlers/playlists.ts:22-36 (handler)

  Core handler function that implements the get_playlist_tracks tool logic by extracting the playlist ID, building query parameters, and calling the Spotify API endpoint /playlists/{id}/tracks.

  async getPlaylistTracks(args: PlaylistTracksArgs) {
    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}/tracks${this.api.buildQueryString(params)}`
    );
  }

• src/index.ts:462-492 (registration)

  Tool registration in the MCP server's listTools response, defining the tool name, description, and input schema.

  name: 'get_playlist_tracks',
  description: 'Get full details of the tracks 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 tracks to return (1-100)',
        minimum: 1,
        maximum: 100
      },
      offset: {
        type: 'number',
        description: 'Optional. Index of the first track to return',
        minimum: 0
      }
    },
    required: ['id']
  },

• src/index.ts:837-843 (registration)

  Dispatch handler in the callTool request that validates arguments and delegates to the playlistsHandler.getPlaylistTracks method.

  case 'get_playlist_tracks': {
    const args = this.validateArgs<PlaylistTracksArgs>(request.params.arguments, ['id']);
    const result = await this.playlistsHandler.getPlaylistTracks(args);
    return {
      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
    };
  }

• src/types/playlists.ts:7-10 (schema)

  TypeScript type definition for the input arguments of get_playlist_tracks, extending common market and pagination parameters.

  export interface PlaylistTracksArgs extends MarketParams, PaginationParams {
    id: string;
    fields?: string;
  }

• src/handlers/playlists.ts:8-10 (helper)

  Helper method used by getPlaylistTracks to normalize playlist ID from Spotify URI or plain ID.

  private extractPlaylistId(id: string): string {
    return id.startsWith('spotify:playlist:') ? id.split(':')[2] : id;
  }