get_categories
Retrieve Spotify's music categories to build browsing interfaces, discover genres, and organize playlists. Returns category names, descriptions, icons, and links for structured music exploration.
Instructions
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
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| country | No | Country code for localized content (e.g., 'US', 'GB') | |
| limit | No | ||
| token | Yes | Spotify access token for authentication |
Implementation Reference
- src/mcp/tools/playlists.ts:433-436 (handler)The MCP tool handler function for 'get_categories' that destructures input arguments and delegates execution to SpotifyService.getCategories method.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)The Zod-based input schema definition for the 'get_categories' tool, specifying required token and optional limit/country parameters.schema: createSchema({ token: commonSchemas.token(), limit: commonSchemas.limit(1, 50, 20), country: commonSchemas.country(), }),
- src/mcp/tools/index.ts:22-36 (registration)Registration of the 'get_categories' tool as part of the aggregated allTools object via spreading playlistTools into the central tools registry used by ToolRegistrar.export const allTools: ToolsRegistry = { ...albumTools, ...artistTools, ...trackTools, ...playlistTools, ...playbackTools, ...userTools, ...searchTools, };
- src/spotify.ts:726-736 (helper)Core implementation in SpotifyService that performs the HTTP request to Spotify API endpoint '/browse/categories' to fetch category data.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); }
- src/mcp/server.ts:14-14 (registration)Instantiation of ToolRegistrar in the MCP server, which loads allTools (including get_categories) and provides handlers/schemas for MCP protocol.const toolRegistrar = new ToolRegistrar(spotifyService);