Spotify MCP Server

Instructions

Implementation Reference

• src/mcp/tools/playlists.ts:381-437 (registration)

  Registration of the 'get_categories' MCP tool within the playlistTools object, including title, description, schema, and handler.
  get_categories: { title: "Get Browse Categories", description: `Explore all available music categories that Spotify uses to organize and classify playlists and content. 🎯 USE CASES: • Build category-based music browsing interfaces • Discover music genres and style classifications • Create organized music discovery experiences • Research music categorization and taxonomy • Build genre-specific playlist recommendation systems 📝 WHAT IT RETURNS: • Complete list of Spotify's music categories • Category names, descriptions, and representative icons • Genre classifications and style groupings • Category popularity and playlist counts • Links to explore category-specific content 🔍 EXAMPLES: • "Show me all music categories on Spotify" • "Get browse categories for music discovery" • "What genres and categories are available?" • "List all music classification categories" 🗂️ CATEGORY TYPES: • Genre categories: Rock, Pop, Hip-Hop, Electronic, etc. • Mood categories: Chill, Party, Focus, Sleep, etc. • Activity categories: Workout, Commute, Gaming, etc. • Demographic categories: Kids, Decades, Regional, etc. • Special categories: New Releases, Charts, Discover, etc. 💡 ORGANIZATION BENEFITS: • Systematic approach to music discovery • Clear classification for different musical styles • Perfect for building browsing interfaces • Helps users navigate vast music catalogs • Professional categorization system 🎯 USE IN APPLICATIONS: • Create category-based navigation menus • Build genre-specific recommendation engines • Organize music content systematically • Provide structured music discovery experiences ⚠️ REQUIREMENTS: • Valid Spotify access token • Categories reflect current Spotify organization`, schema: createSchema({ token: commonSchemas.token(), limit: commonSchemas.limit(1, 50, 20), country: commonSchemas.country(), }), handler: async (args: any, spotifyService: SpotifyService) => { const { token, limit = 20, country } = args; return await spotifyService.getCategories(token, limit, country); }, },
• src/mcp/tools/playlists.ts:433-436 (handler)

  The handler function for the 'get_categories' tool, which extracts arguments and delegates to SpotifyService.getCategories.
  handler: async (args: any, spotifyService: SpotifyService) => { const { token, limit = 20, country } = args; return await spotifyService.getCategories(token, limit, country); },
• src/mcp/tools/playlists.ts:428-432 (schema)

  Input schema validation for the get_categories tool parameters: token, limit, country.
  schema: createSchema({ token: commonSchemas.token(), limit: commonSchemas.limit(1, 50, 20), country: commonSchemas.country(), }),
• src/spotify.ts:726-736 (helper)

  SpotifyService helper method that implements the actual API call to Spotify's browse/categories endpoint.
  async getCategories( token: string, limit: number = 20, country: string | null = null ): Promise<{ categories: PagingObject<SpotifyCategory> }> { const params: Record<string, any> = { limit: Math.min(limit, 50) }; if (country) params.country = country; return await this.makeRequest<{ categories: PagingObject<SpotifyCategory>; }>("browse/categories", token, params); }