Spotify MCP Server

Instructions

Implementation Reference

• src/read.ts:322-382 (handler)

  The complete tool object definition for 'getRecentlyPlayed', including inline Zod schema for optional 'limit' parameter (1-50), description, and the async handler function. The handler uses handleSpotifyRequest to call spotifyApi.player.getRecentlyPlayedTracks(limit), processes the history items using isTrack helper, formats each track with name, artists, duration, ID, and played_at timestamp, and returns a markdown-formatted text response or error message if none.

  const getRecentlyPlayed: tool<{
    limit: z.ZodOptional<z.ZodNumber>;
  }> = {
    name: 'getRecentlyPlayed',
    description: 'Get a list of recently played tracks on Spotify',
    schema: {
      limit: z
        .number()
        .min(1)
        .max(50)
        .optional()
        .describe('Maximum number of tracks to return (1-50)'),
    },
    handler: async (args, _extra: SpotifyHandlerExtra) => {
      const { limit = 50 } = args;
  
      const history = await handleSpotifyRequest(async (spotifyApi) => {
        return await spotifyApi.player.getRecentlyPlayedTracks(
          limit as MaxInt<50>,
        );
      });
  
      if (history.items.length === 0) {
        return {
          content: [
            {
              type: 'text',
              text: "You don't have any recently played tracks on Spotify",
            },
          ],
        };
      }
  
      const formattedHistory = history.items
        .map((item, i) => {
          const track = item.track;
          if (!track) return `${i + 1}. [Removed track]`;
  
          if (isTrack(track)) {
            const artists = track.artists.map((a) => a.name).join(', ');
            const duration = formatDuration(track.duration_ms);
            const playedAt = item.played_at
              ? new Date(item.played_at).toLocaleString()
              : 'Unknown time';
            return `${i + 1}. "${track.name}" by ${artists} (${duration}) - ID: ${track.id} - Played at: ${playedAt}`;
          }
  
          return `${i + 1}. Unknown item`;
        })
        .join('\n');
  
      return {
        content: [
          {
            type: 'text',
            text: `# Recently Played Tracks\n\n${formattedHistory}`,
          },
        ],
      };
    },
  };

• src/read.ts:603-612 (registration)

  Local registration: getRecentlyPlayed is included in the exported 'readTools' array alongside other read-related tools.

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

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

  Global registration: All tools from readTools (including getRecentlyPlayed), playTools, and albumTools are registered to the MCP server by iterating and calling server.tool() with each tool's name, description, schema, and handler.

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

• src/read.ts:6-14 (helper)

  Helper function isTrack used in the handler to type-guard and validate track items before formatting.

  function isTrack(item: any): item is SpotifyTrack {
    return (
      item &&
      item.type === 'track' &&
      Array.isArray(item.artists) &&
      item.album &&
      typeof item.album.name === 'string'
    );
  }