search_albums
Search Spotify for albums by artist, title, genre, or keywords to find discographies, themed collections, or rare releases. Returns relevant results with details like release year, artwork, and track count.
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 |
|---|---|---|---|
| limit | No | ||
| query | Yes | Search query for albums (album name, artist, keywords) | |
| token | Yes | Spotify access token for authentication |
Implementation Reference
- src/mcp/tools/albums.ts:166-169 (handler)The MCP tool handler function for 'search_albums', which destructures the input arguments and delegates to the SpotifyService.searchAlbums method.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)The input schema definition for the 'search_albums' tool, specifying token, query, and optional limit parameters with validation.schema: createSchema({ token: commonSchemas.token(), query: commonSchemas.searchQuery("albums (album name, artist, keywords)"), limit: commonSchemas.limit(1, 50, 20), }),
- src/mcp/tools/index.ts:22-36 (registration)Central tools registry where albumTools (containing search_albums) is spread into the allTools object used by ToolRegistrar.export const allTools: ToolsRegistry = { ...albumTools, ...artistTools, ...trackTools, ...playlistTools, ...playbackTools, ...userTools, ...searchTools, };
- src/spotify.ts:365-376 (helper)The SpotifyService helper method implementing the core search logic by calling Spotify's search API 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); }
- src/mcp/server.ts:14-14 (registration)Instantiation of ToolRegistrar in the MCP server, which generates the final MCP tool definitions and handlers for all tools including search_albums.const toolRegistrar = new ToolRegistrar(spotifyService);