search_music
Search Spotify's music catalog to find tracks, albums, artists, and playlists using keywords, genres, or partial information for music discovery and retrieval.
Instructions
Perform comprehensive music search across all Spotify content types with intelligent filtering and ranking.
🎯 USE CASES: • Universal music discovery across tracks, albums, artists, and playlists • Build intelligent search interfaces for music applications • Find specific songs when you only remember partial information • Discover new music based on keywords, moods, or themes • Create dynamic search-based music recommendations
📝 WHAT IT RETURNS: • Multi-type search results (tracks, artists, albums, playlists) • Relevance-ranked results based on Spotify's search algorithms • Complete metadata for each result type • Popularity scores and user engagement metrics • Links to explore each result in detail
🔍 EXAMPLES: • "Search for 'upbeat dance music' in tracks" • "Find 'acoustic guitar' content across all types" • "Look for 'Beatles' in artists and albums" • "Search for '90s hip hop' in playlists"
🎵 SEARCH TYPES: • 'track' - Individual songs and recordings • 'album' - Full album releases and EPs • 'artist' - Musicians, bands, and performers • 'playlist' - User and editorial playlists • 'show' - Podcasts and audio shows • 'episode' - Individual podcast episodes
💡 SEARCH STRATEGIES: • Use descriptive keywords: "chill indie folk" • Include artist names: "Taylor Swift love songs" • Try genre combinations: "electronic jazz fusion" • Use mood descriptors: "energetic workout beats" • Include decades: "80s synthwave nostalgia"
🔍 ADVANCED FEATURES: • Intelligent typo correction and suggestions • Context-aware search ranking • Market-specific availability filtering • Real-time search result updates • Multi-language search support
⚠️ REQUIREMENTS: • Valid Spotify access token • Search queries should be at least 2 characters long
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| token | Yes | Spotify access token for authentication | |
| query | Yes | Search query for music content (keyword, title, artist) | |
| type | No | track | |
| limit | No |
Implementation Reference
- src/mcp/tools/search.ts:62-65 (handler)The handler function that executes the core logic of the 'search_music' tool by calling the Spotify service.handler: async (args: any, spotifyService: SpotifyService) => { const { token, query, type = "track", limit = 10 } = args; return await spotifyService.searchMusic(token, query, type, limit); },
- src/mcp/tools/search.ts:54-61 (schema)The input schema defining parameters for the 'search_music' tool: token, query, type, limit.schema: createSchema({ token: commonSchemas.token(), query: commonSchemas.searchQuery( "music content (keyword, title, artist)" ), type: commonSchemas.searchType(), limit: commonSchemas.limit(1, 50, 10), }),
- src/mcp/tools/index.ts:22-36 (registration)Registration of searchTools (including 'search_music') into the central allTools registry used by the MCP ToolRegistrar.export const allTools: ToolsRegistry = { ...albumTools, ...artistTools, ...trackTools, ...playlistTools, ...playbackTools, ...userTools, ...searchTools, };
- src/spotify.ts:479-491 (helper)The SpotifyService.searchMusic helper method that performs the actual Spotify API search call.async searchMusic( token: string, query: string, type: "track" | "album" | "artist" | "playlist" = "track", limit: number = 10 ): Promise<SearchResult> { const params = { q: query, type: type, limit: Math.min(limit, 50), }; return await this.makeRequest<SearchResult>("search", token, params); }