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