Spotify MCP Server

Instructions

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);
      },
    },