Spotify MCP Server

Instructions

Implementation Reference

• src/albums.ts:120-174 (handler)

  The main handler function that fetches album tracks from Spotify API, handles pagination, formats track list with artists and durations, and returns formatted text response.

  handler: async (args, _extra: SpotifyHandlerExtra) => {
    const { albumId, limit = 20, offset = 0 } = args;
  
    try {
      const tracks = await handleSpotifyRequest(async (spotifyApi) => {
        return await spotifyApi.albums.tracks(
          albumId,
          undefined,
          limit as MaxInt<50>,
          offset,
        );
      });
  
      if (tracks.items.length === 0) {
        return {
          content: [
            {
              type: 'text',
              text: 'No tracks found in this album',
            },
          ],
        };
      }
  
      const formattedTracks = tracks.items
        .map((track, i) => {
          if (!track) return `${i + 1}. [Track not found]`;
  
          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}`;
        })
        .join('\n');
  
      return {
        content: [
          {
            type: 'text',
            text: `# Album Tracks (${offset + 1}-${offset + tracks.items.length} of ${tracks.total})\n\n${formattedTracks}`,
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error getting album tracks: ${
              error instanceof Error ? error.message : String(error)
            }`,
          },
        ],
      };
    }
  },

• src/albums.ts:106-119 (schema)

  Zod schema defining input parameters: albumId (required string), limit (optional 1-50), offset (optional >=0).

  schema: {
    albumId: z.string().describe('The Spotify ID of the album'),
    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/albums.ts:299-304 (registration)

  Exports an array of album-related tools including getAlbumTracks, likely used for MCP tool registration.

  export const albumTools = [
    getAlbums,
    getAlbumTracks,
    saveOrRemoveAlbumForUser,
    checkUsersSavedAlbums,
  ];