get_top_artists
Identify your most played Spotify artists across different time ranges for insights into your music preferences, playlist creation, and sharing trends.
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 |
|---|---|---|---|
| limit | No | ||
| timeRange | No | medium_term | |
| token | Yes | Spotify access token for authentication |
Implementation Reference
- src/spotify.ts:301-315 (handler)Core handler function in SpotifyService that queries the Spotify API endpoint 'me/top/artists' to retrieve the user's top artists based on listening history, time range, and limit.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:229-271 (registration)Registers the MCP tool 'get_top_artists' with detailed description, input schema validation, and a handler that delegates to SpotifyService.getTopArtists.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); }, },
- src/mcp/tools/artists.ts:262-266 (schema)Defines the input schema for the tool using common schema builders for token, timeRange (short_term|medium_term|long_term), and limit (1-50).schema: createSchema({ token: commonSchemas.token(), timeRange: commonSchemas.timeRange(), limit: commonSchemas.limit(1, 50, 20), }),