Spotify MCP Server

Instructions

Implementation Reference

• src/read.ts:183-234 (handler)

  Full implementation of the getMyPlaylists tool, including schema, description, and handler function that retrieves and formats the user's Spotify playlists using the Spotify API.

  const getMyPlaylists: tool<{
    limit: z.ZodOptional<z.ZodNumber>;
  }> = {
    name: 'getMyPlaylists',
    description: "Get a list of the current user's playlists on Spotify",
    schema: {
      limit: z
        .number()
        .min(1)
        .max(50)
        .optional()
        .describe('Maximum number of playlists to return (1-50)'),
    },
    handler: async (args, _extra: SpotifyHandlerExtra) => {
      const { limit = 50 } = args;
  
      const playlists = await handleSpotifyRequest(async (spotifyApi) => {
        return await spotifyApi.currentUser.playlists.playlists(
          limit as MaxInt<50>,
        );
      });
  
      if (playlists.items.length === 0) {
        return {
          content: [
            {
              type: 'text',
              text: "You don't have any playlists on Spotify",
            },
          ],
        };
      }
  
      const formattedPlaylists = playlists.items
        .map((playlist, i) => {
          const tracksTotal = playlist.tracks?.total ? playlist.tracks.total : 0;
          return `${i + 1}. "${playlist.name}" (${tracksTotal} tracks) - ID: ${
            playlist.id
          }`;
        })
        .join('\n');
  
      return {
        content: [
          {
            type: 'text',
            text: `# Your Spotify Playlists\n\n${formattedPlaylists}`,
          },
        ],
      };
    },
  };

• src/read.ts:531-539 (registration)

  The getMyPlaylists tool is included in the exported readTools array for grouping read operations.

  export const readTools = [
    searchSpotify,
    getNowPlaying,
    getMyPlaylists,
    getPlaylistTracks,
    getRecentlyPlayed,
    getUsersSavedTracks,
    getQueue,
  ];

• src/index.ts:12-14 (registration)

  Registration of all tools, including getMyPlaylists via readTools, to the MCP server using server.tool().

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

• src/utils.ts:282-301 (helper)

  Utility function handleSpotifyRequest used in the getMyPlaylists handler to execute Spotify API calls with proper authentication and error handling.

  export async function handleSpotifyRequest<T>(
    action: (spotifyApi: SpotifyApi) => Promise<T>,
  ): Promise<T> {
    try {
      const spotifyApi = createSpotifyApi();
      return await action(spotifyApi);
    } catch (error) {
      // Skip JSON parsing errors as these are actually successful operations
      const errorMessage = error instanceof Error ? error.message : String(error);
      if (
        errorMessage.includes('Unexpected token') ||
        errorMessage.includes('Unexpected non-whitespace character') ||
        errorMessage.includes('Exponent part is missing a number in JSON')
      ) {
        return undefined as T;
      }
      // Rethrow other errors
      throw error;
    }
  }