Spotify MCP Server

Instructions

Implementation Reference

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

  The handler function that executes the tool logic: fetches album tracks from Spotify API using handleSpotifyRequest, formats them with artist names and durations, handles pagination, and returns formatted text content or error.

    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 input schema defining parameters: albumId (required string), limit (optional number 1-50), offset (optional number >=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/index.ts:12-14 (registration)

  Main registration of all tools (including getAlbumTracks via albumTools) to the MCP server using server.tool().

  [...readTools, ...playTools, ...albumTools].forEach((tool) => {
    server.tool(tool.name, tool.description, tool.schema, tool.handler);
  });

• src/albums.ts:299-304 (registration)

  Local registration/grouping of album tools including getAlbumTracks for export to main index.

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