get_top_tracks
Retrieve your most played Spotify tracks across different time periods to analyze listening patterns, create personalized playlists, and share music preferences. Works with short, medium, and long-term listening history.
Instructions
Discover your most listened-to tracks based on actual listening history across different time periods.
🎯 USE CASES: • Understand your personal music listening patterns • Create "Year in Music" summaries and personal statistics • Build playlists based on your actual favorite songs • Share your top music with friends and social media • Track changes in musical preferences over time
📝 WHAT IT RETURNS: • Your most played tracks ranked by listening frequency • Track information with play count estimates • Time-period specific listening statistics • Artist and album information for top tracks • Insights into your musical preferences and habits
🔍 EXAMPLES: • "What are my top tracks this month?" • "Show my most listened songs of all time" • "Get my top 20 tracks from the last 6 months" • "What songs have I been playing on repeat recently?"
⏰ TIME PERIODS: • 'short_term' - Last 4 weeks of listening history • 'medium_term' - Last 6 months of musical activity • 'long_term' - All-time listening patterns and favorites • Compare across periods to see taste evolution
📊 LISTENING INSIGHTS: • Discover patterns in your music consumption • Identify your most-loved songs across different eras • Perfect for building "best of" personal playlists • Great for music discovery based on your actual preferences • Useful for understanding your musical identity
💡 PERSONAL ANALYTICS: • Track how your taste evolves over time • Identify seasonal listening patterns • Use for building recommendation systems • Share musical identity with others • Create data-driven personal playlists
⚠️ REQUIREMENTS: • Valid Spotify access token with user-top-read scope • Sufficient listening history for accurate results
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| timeRange | No | medium_term | |
| token | Yes | Spotify access token for authentication |
Implementation Reference
- src/mcp/tools/tracks.ts:316-319 (handler)MCP tool handler function that extracts parameters (token, timeRange, limit) and delegates execution to SpotifyService.getTopTrackshandler: async (args: any, spotifyService: SpotifyService) => { const { token, timeRange = "medium_term", limit = 20 } = args; return await spotifyService.getTopTracks(token, timeRange, limit); },
- src/mcp/tools/tracks.ts:311-315 (schema)Zod input schema definition for the get_top_tracks tool parametersschema: createSchema({ token: commonSchemas.token(), timeRange: commonSchemas.timeRange(), limit: commonSchemas.limit(1, 50, 20), }),
- src/mcp/tools/index.ts:22-36 (registration)Includes trackTools (containing get_top_tracks) in the central allTools registry used for MCP tool registrationexport const allTools: ToolsRegistry = { ...albumTools, ...artistTools, ...trackTools, ...playlistTools, ...playbackTools, ...userTools, ...searchTools, };
- src/mcp/server.ts:49-80 (registration)MCP server CallTool request handler that dynamically creates and executes tool handlers from ToolRegistrar, including get_top_tracksserver.setRequestHandler(CallToolRequestSchema, async (request) => { const { name, arguments: args } = request.params; try { const toolHandler = toolRegistrar.createToolHandler(name); const result = await toolHandler(args || {}); return { content: [ { type: "text", text: typeof result === "string" ? result : JSON.stringify(result, null, 2), }, ], }; } catch (error) { return { content: [ { type: "text", text: `Error executing tool '${name}': ${ error instanceof Error ? error.message : String(error) }`, }, ], isError: true, }; } });
- src/spotify.ts:285-299 (helper)Core implementation in SpotifyService that calls Spotify API endpoint /me/top/tracks with time_range and limit parametersasync getTopTracks( token: string, timeRange: "short_term" | "medium_term" | "long_term" = "medium_term", limit: number = 20 ): Promise<TopItemsResponse<SpotifyTrack>> { const params = { time_range: timeRange, limit: Math.min(limit, 50), }; return await this.makeRequest<TopItemsResponse<SpotifyTrack>>( "me/top/tracks", token, params ); }