getAlbums
Retrieve detailed Spotify album information by providing album IDs, enabling access to track lists, release dates, and artist data for up to 20 albums.
Instructions
Get detailed information about one or more albums by their Spotify IDs
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| albumIds | Yes | A single album ID or array of album IDs (max 20) |
Implementation Reference
- src/albums.ts:17-96 (handler)The handler function that implements the core logic of the getAlbums tool. It processes albumIds input, fetches album data from Spotify API using handleSpotifyRequest, handles single or multiple albums, formats the response as markdown text blocks, and catches errors.handler: async (args, _extra: SpotifyHandlerExtra) => { const { albumIds } = args; const ids = Array.isArray(albumIds) ? albumIds : [albumIds]; if (ids.length === 0) { return { content: [ { type: 'text', text: 'Error: No album IDs provided', }, ], }; } try { const albums = await handleSpotifyRequest(async (spotifyApi) => { return ids.length === 1 ? [await spotifyApi.albums.get(ids[0])] : await spotifyApi.albums.get(ids); }); if (albums.length === 0) { return { content: [ { type: 'text', text: 'No albums found for the provided IDs', }, ], }; } if (albums.length === 1) { const album = albums[0]; const artists = album.artists.map((a) => a.name).join(', '); const releaseDate = album.release_date; const totalTracks = album.total_tracks; const albumType = album.album_type; return { content: [ { type: 'text', text: `# Album Details\n\n**Name**: "${album.name}"\n**Artists**: ${artists}\n**Release Date**: ${releaseDate}\n**Type**: ${albumType}\n**Total Tracks**: ${totalTracks}\n**ID**: ${album.id}`, }, ], }; } const formattedAlbums = albums .map((album, i) => { if (!album) return `${i + 1}. [Album not found]`; const artists = album.artists.map((a) => a.name).join(', '); return `${i + 1}. "${album.name}" by ${artists} (${album.release_date}) - ${album.total_tracks} tracks - ID: ${album.id}`; }) .join('\n'); return { content: [ { type: 'text', text: `# Multiple Albums\n\n${formattedAlbums}`, }, ], }; } catch (error) { return { content: [ { type: 'text', text: `Error getting albums: ${ error instanceof Error ? error.message : String(error) }`, }, ], }; } },
- src/albums.ts:12-16 (schema)Zod schema defining the input for getAlbums: albumIds as string or array of strings (max 20).schema: { albumIds: z .union([z.string(), z.array(z.string()).max(20)]) .describe('A single album ID or array of album IDs (max 20)'), },
- src/index.ts:12-14 (registration)Registers the getAlbums tool (included in albumTools) with the MCP server by calling server.tool() for each tool in the combined array.[...readTools, ...playTools, ...albumTools].forEach((tool) => { server.tool(tool.name, tool.description, tool.schema, tool.handler); });
- src/albums.ts:299-304 (registration)Exports array of album-related tools including getAlbums for registration in index.ts.export const albumTools = [ getAlbums, getAlbumTracks, saveOrRemoveAlbumForUser, checkUsersSavedAlbums, ];