search_albums
Search Spotify's music catalog to find albums by artist, title, keywords, genre, or release year. Get detailed results including artwork, track counts, and popularity metrics.
Instructions
Search for albums using flexible keywords, artist names, or album titles to discover music.
🎯 USE CASES: • Finding albums when you only remember partial information • Discovering discographies of new artists • Searching for concept albums or themed collections • Finding albums by genre, mood, or era • Locating rare releases, deluxe editions, or remastered versions
📝 WHAT IT RETURNS: • Ranked search results based on relevance • Album names, artists, and release years • Album artwork and Spotify popularity metrics • Genre information and track counts • External URLs and availability information
🔍 EXAMPLES: • "Search for albums by 'Pink Floyd'" • "Find albums with 'greatest hits' in the title" • "Search for 'jazz piano' albums" • "Look for albums containing 'live' or 'concert'" • "Find albums released in '1969'"
💡 SEARCH TIPS: • Use quotes for exact phrase matching: "Abbey Road" • Combine artist and album names: "Beatles White Album" • Use genre keywords: "progressive rock", "indie folk" • Include year ranges: "1970s rock albums" • Try alternate spellings or abbreviations
⚠️ REQUIREMENTS: • Valid Spotify access token • Search query with meaningful keywords
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| token | Yes | Spotify access token for authentication | |
| query | Yes | Search query for albums (album name, artist, keywords) | |
| limit | No |
Implementation Reference
- src/mcp/tools/albums.ts:166-169 (handler)Handler function for the 'search_albums' tool. It extracts arguments (token, query, limit) and delegates to SpotifyService.searchAlbums.
handler: async (args: any, spotifyService: SpotifyService) => { const { token, query, limit = 20 } = args; return await spotifyService.searchAlbums(token, query, limit); }, - src/mcp/tools/albums.ts:161-165 (schema)Input schema definition for the 'search_albums' tool using createSchema, defining token, query, and optional limit parameters.
schema: createSchema({ token: commonSchemas.token(), query: commonSchemas.searchQuery("albums (album name, artist, keywords)"), limit: commonSchemas.limit(1, 50, 20), }), - src/mcp/tools/albums.ts:126-170 (registration)Complete tool definition and registration of 'search_albums' within the albumTools object, including title, description, schema, and handler.
search_albums: { title: "Search Albums", description: `Search for albums using flexible keywords, artist names, or album titles to discover music. 🎯 USE CASES: • Finding albums when you only remember partial information • Discovering discographies of new artists • Searching for concept albums or themed collections • Finding albums by genre, mood, or era • Locating rare releases, deluxe editions, or remastered versions 📝 WHAT IT RETURNS: • Ranked search results based on relevance • Album names, artists, and release years • Album artwork and Spotify popularity metrics • Genre information and track counts • External URLs and availability information 🔍 EXAMPLES: • "Search for albums by 'Pink Floyd'" • "Find albums with 'greatest hits' in the title" • "Search for 'jazz piano' albums" • "Look for albums containing 'live' or 'concert'" • "Find albums released in '1969'" 💡 SEARCH TIPS: • Use quotes for exact phrase matching: "Abbey Road" • Combine artist and album names: "Beatles White Album" • Use genre keywords: "progressive rock", "indie folk" • Include year ranges: "1970s rock albums" • Try alternate spellings or abbreviations ⚠️ REQUIREMENTS: • Valid Spotify access token • Search query with meaningful keywords`, schema: createSchema({ token: commonSchemas.token(), query: commonSchemas.searchQuery("albums (album name, artist, keywords)"), limit: commonSchemas.limit(1, 50, 20), }), handler: async (args: any, spotifyService: SpotifyService) => { const { token, query, limit = 20 } = args; return await spotifyService.searchAlbums(token, query, limit); }, }, - src/spotify.ts:365-376 (helper)SpotifyService method that performs the actual album search by calling Spotify's /search API endpoint with type='album'.
async searchAlbums( token: string, query: string, limit: number = 20 ): Promise<SearchResult> { const params = { q: query, type: "album", limit: Math.min(limit, 50), }; return await this.makeRequest<SearchResult>("search", token, params); }