get_recently_played
Retrieve your recent Spotify listening history with timestamps to track music activity, rediscover songs, and analyze listening patterns.
Instructions
Access your complete recent listening history with timestamps for tracking music activity and rediscovering songs.
🎯 USE CASES: • Track recent music discovery and listening habits • Rediscover songs you heard but forgot to save • Build "Recently Discovered" playlists from history • Monitor listening patterns and music consumption • Create activity logs for music journaling
📝 WHAT IT RETURNS: • Chronological list of recently played tracks • Exact timestamps of when each track was played • Track information including artist, album, and duration • Play context (playlist, album, or individual play) • Device information where tracks were played
🔍 EXAMPLES: • "What have I been listening to recently?" • "Show my last 50 played tracks with timestamps" • "What songs did I discover today?" • "Get my recent listening history for this week"
⏰ LISTENING HISTORY: • Shows exact sequence of recent music activity • Includes partial plays and skips • Perfect for rediscovering forgotten gems • Great for tracking music exploration sessions • Useful for building "recently discovered" collections
💡 HISTORY BENEFITS: • Never lose track of songs you enjoyed • Monitor listening habits and patterns • Perfect for building discovery-based playlists • Great for social sharing of recent finds • Essential for music tracking and journaling
🎵 REDISCOVERY OPPORTUNITIES: • Find songs you heard but didn't save • Track down music from specific listening sessions • Identify patterns in your music exploration • Perfect for playlist creation from recent activity
⚠️ REQUIREMENTS: • Valid Spotify access token with user-read-recently-played scope • History shows approximately last 50 tracks played
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| token | Yes | Spotify access token for authentication | |
| limit | No |
Implementation Reference
- src/mcp/tools/tracks.ts:373-376 (handler)The handler function for the 'get_recently_played' MCP tool. It destructures the token and limit from args and delegates to SpotifyService.getRecentlyPlayed.
handler: async (args: any, spotifyService: SpotifyService) => { const { token, limit = 20 } = args; return await spotifyService.getRecentlyPlayed(token, limit); }, - src/mcp/tools/tracks.ts:369-372 (schema)The input schema for the tool, defining required 'token' and optional 'limit' parameters using common schema builders.
schema: createSchema({ token: commonSchemas.token(), limit: commonSchemas.limit(1, 50, 20), }), - src/mcp/tools/index.ts:22-36 (registration)Central tools registry where trackTools (containing get_recently_played) is spread into allTools, used by ToolRegistrar for MCP tool registration.
export const allTools: ToolsRegistry = { ...albumTools, ...artistTools, ...trackTools, ...playlistTools, ...playbackTools, ...userTools, ...searchTools, }; - src/spotify.ts:604-616 (helper)SpotifyService method that implements the core logic by calling Spotify API endpoint /me/player/recently-played to fetch user's recently played tracks.
async getRecentlyPlayed( token: string, limit: number = 20 ): Promise<PagingObject<RecentlyPlayedItem>> { const params = { limit: Math.min(limit, 50), }; return await this.makeRequest<PagingObject<RecentlyPlayedItem>>( "me/player/recently-played", token, params ); }