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