getRecentlyPlayed

Retrieve a list of recently played Spotify tracks to review listening history or resume playback. Specify a limit (1-50) to control the number of tracks returned.

Instructions

Get a list of recently played tracks on Spotify

Input Schema

TableJSON Schema

Name	Required	Description	Default
`limit`	No	Maximum number of tracks to return (1-50)

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'
  );
}

Spotify MCP Server