get_top_artists
Retrieve your most listened-to Spotify artists over customizable time periods to analyze listening habits and discover music preferences.
Instructions
Analyze your personal listening habits to discover your most played artists over different time periods.
🎯 USE CASES: • Understanding your personal music taste evolution • Creating "Year in Music" summaries and statistics • Building playlists based on your actual listening habits • Sharing your music taste with friends and social media • Discovering patterns in your music preferences
📝 WHAT IT RETURNS: • Your most listened-to artists ranked by play time • Artist names, images, and genre breakdowns • Listening statistics and time-period comparisons • Popularity scores and follower information • Insights into your musical preferences
🔍 EXAMPLES: • "Who are my top artists this month?" • "Show my most played artists of all time" • "Get my top 10 artists from the last 6 months" • "What artists have I been listening to most recently?"
⏰ TIME RANGES:
• 'short_term' - Last 4 weeks of listening
• 'medium_term' - Last 6 months of listening
• 'long_term' - All-time listening history
• Compare across different periods for insights
⚠️ REQUIREMENTS: • Valid Spotify access token with user-top-read scope • Sufficient listening history for accurate results
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| token | Yes | Spotify access token for authentication | |
| timeRange | No | medium_term | |
| limit | No |
Implementation Reference
- src/spotify.ts:301-315 (handler)The core handler function that executes the tool logic by making an authenticated API request to Spotify's 'me/top/artists' endpoint to retrieve the user's top artists over the specified time range.
async getTopArtists( token: string, timeRange: "short_term" | "medium_term" | "long_term" = "medium_term", limit: number = 20 ): Promise<TopItemsResponse<SpotifyArtist>> { const params = { time_range: timeRange, limit: Math.min(limit, 50), }; return await this.makeRequest<TopItemsResponse<SpotifyArtist>>( "me/top/artists", token, params ); } - src/mcp/tools/artists.ts:262-266 (schema)Defines the input schema for the 'get_top_artists' tool, validating token, timeRange (short_term|medium_term|long_term), and limit parameters.
schema: createSchema({ token: commonSchemas.token(), timeRange: commonSchemas.timeRange(), limit: commonSchemas.limit(1, 50, 20), }), - src/mcp/tools/artists.ts:229-271 (registration)Registers the 'get_top_artists' MCP tool with title, detailed description, schema, and wrapper handler that delegates to the SpotifyService.getTopArtists method.
get_top_artists: { title: "Get User's Top Artists", description: `Analyze your personal listening habits to discover your most played artists over different time periods. 🎯 USE CASES: • Understanding your personal music taste evolution • Creating "Year in Music" summaries and statistics • Building playlists based on your actual listening habits • Sharing your music taste with friends and social media • Discovering patterns in your music preferences 📝 WHAT IT RETURNS: • Your most listened-to artists ranked by play time • Artist names, images, and genre breakdowns • Listening statistics and time-period comparisons • Popularity scores and follower information • Insights into your musical preferences 🔍 EXAMPLES: • "Who are my top artists this month?" • "Show my most played artists of all time" • "Get my top 10 artists from the last 6 months" • "What artists have I been listening to most recently?" ⏰ TIME RANGES: • 'short_term' - Last 4 weeks of listening • 'medium_term' - Last 6 months of listening • 'long_term' - All-time listening history • Compare across different periods for insights ⚠️ 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.getTopArtists(token, timeRange, limit); }, },