Spotify MCP Server

Instructions

Implementation Reference

• src/read.ts:451-528 (handler)

  The handler function that implements the core logic of the getQueue tool. It fetches the current Spotify queue, handles the currently playing track and upcoming tracks, formats them nicely, and returns a markdown-formatted response.

  handler: async (args, _extra: SpotifyHandlerExtra) => {
    const { limit = 10 } = args;
  
    try {
      const queue = await handleSpotifyRequest(async (spotifyApi) => {
        return await spotifyApi.player.getUsersQueue();
      });
  
      const current = (queue as any)?.currently_playing;
      const upcoming = ((queue as any)?.queue ?? []) as any[];
  
      const header = '# Spotify Queue\n\n';
  
      let currentText = 'Nothing is currently playing';
      if (current) {
        const name = current?.name ?? 'Unknown';
        const artists = Array.isArray(current?.artists)
          ? (current.artists as Array<{ name: string }>)
              .map((a) => a.name)
              .join(', ')
          : 'Unknown';
        const duration =
          typeof current?.duration_ms === 'number'
            ? formatDuration(current.duration_ms)
            : 'Unknown';
        currentText = `Currently Playing: "${name}" by ${artists} (${duration})`;
      }
  
      if (upcoming.length === 0) {
        return {
          content: [
            {
              type: 'text',
              text: `${header}${currentText}\n\nNo upcoming items in the queue`,
            },
          ],
        };
      }
  
      const toShow = upcoming.slice(0, limit);
      const formatted = toShow
        .map((track, i) => {
          const name = track?.name ?? 'Unknown';
          const artists = Array.isArray(track?.artists)
            ? (track.artists as Array<{ name: string }>)
                .map((a) => a.name)
                .join(', ')
            : 'Unknown';
          const duration =
            typeof track?.duration_ms === 'number'
              ? formatDuration(track.duration_ms)
              : 'Unknown';
          const id = track?.id ?? 'Unknown';
          return `${i + 1}. "${name}" by ${artists} (${duration}) - ID: ${id}`;
        })
        .join('\n');
  
      return {
        content: [
          {
            type: 'text',
            text: `${header}${currentText}\n\nNext ${toShow.length} in queue:\n\n${formatted}`,
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error fetching queue: ${
              error instanceof Error ? error.message : String(error)
            }`,
          },
        ],
      };
    }
  },

• src/read.ts:443-450 (schema)

  The Zod input schema for the getQueue tool, defining an optional 'limit' parameter between 1 and 50.

  schema: {
    limit: z
      .number()
      .min(1)
      .max(50)
      .optional()
      .describe('Maximum number of upcoming items to show (1-50)'),
  },

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

  The getQueue tool is registered by being included in the exported readTools array, which collects all read-related Spotify tools for the MCP server.

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