search_music
Search Spotify for tracks, albums, artists, and playlists using keywords, moods, or themes. Retrieve ranked results with metadata and links for music discovery or app integration.
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 |
|---|---|---|---|
| limit | No | ||
| query | Yes | Search query for music content (keyword, title, artist) | |
| token | Yes | Spotify access token for authentication | |
| type | No | track |
Implementation Reference
- src/mcp/tools/search.ts:62-65 (handler)The MCP tool handler for 'search_music' that extracts parameters and delegates the search to SpotifyService.searchMusic.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 for the 'search_music' tool, defining parameters: token, query, type, and 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 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 request.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); }
- src/mcp/server.ts:13-14 (registration)Initialization of ToolRegistrar in the MCP server, which loads allTools including 'search_music' for MCP tool handling.const spotifyService = new SpotifyService(); const toolRegistrar = new ToolRegistrar(spotifyService);