Spotify MCP Server

Instructions

Implementation Reference

• src/mcp/tools/tracks.ts:316-319 (handler)

  The handler function for the 'get_top_tracks' MCP tool. It destructures the input arguments (token, timeRange, limit) and delegates execution to SpotifyService.getTopTracks.
  handler: 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 schema definition for the 'get_top_tracks' tool inputs: Spotify access token, time range (short_term, medium_term, long_term), and optional limit (default 20).
  schema: createSchema({ token: commonSchemas.token(), timeRange: commonSchemas.timeRange(), limit: commonSchemas.limit(1, 50, 20), }),
• src/mcp/tools/tracks.ts:264-320 (registration)

  Full tool registration object for 'get_top_tracks' within the trackTools export, including title, description, schema, and handler. This object is imported and spread into the main allTools registry.
  get_top_tracks: { title: "Get User's Top Tracks", description: `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`, schema: createSchema({ token: commonSchemas.token(), timeRange: commonSchemas.timeRange(), limit: commonSchemas.limit(1, 50, 20), }), handler: async (args: any, spotifyService: SpotifyService) => { const { token, timeRange = "medium_term", limit = 20 } = args; return await spotifyService.getTopTracks(token, timeRange, limit); }, },
• src/spotify.ts:285-299 (helper)

  Core implementation in SpotifyService that performs the actual Spotify API call to retrieve user's top tracks for the specified time range and limit.
  async 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 ); }
• src/mcp/tools/index.ts:22-36 (registration)

  Central tools registry where trackTools (containing get_top_tracks) is spread into allTools, making it available to the ToolRegistrar for MCP tool exposure.
  export const allTools: ToolsRegistry = { ...albumTools, ...artistTools, ...trackTools, ...playlistTools, ...playbackTools, ...userTools, ...searchTools, };