getAlbums
Retrieve detailed album information using Spotify IDs with the MCP Server tool, supporting single or multiple album queries (up to 20 IDs).
Instructions
Get detailed information about one or more albums by their Spotify IDs
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| albumIds | Yes | A single album ID or array of album IDs (max 20) |
Input Schema (JSON Schema)
{
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"albumIds": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"type": "string"
},
"maxItems": 20,
"type": "array"
}
],
"description": "A single album ID or array of album IDs (max 20)"
}
},
"required": [
"albumIds"
],
"type": "object"
}
Implementation Reference
- src/albums.ts:17-96 (handler)Handler function that fetches and formats details for one or more Spotify albums using the provided IDs, handling errors and different response formats for single vs multiple albums.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 parameter 'albumIds' as a string or array of up to 20 album IDs.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/albums.ts:299-304 (registration)getAlbums is included in the exported albumTools array, which collects album-related tools for registration.export const albumTools = [ getAlbums, getAlbumTracks, saveOrRemoveAlbumForUser, checkUsersSavedAlbums, ];
- src/index.ts:12-14 (registration)All tools from readTools, playTools, and albumTools (including getAlbums) are registered with the MCP server via server.tool calls.[...readTools, ...playTools, ...albumTools].forEach((tool) => { server.tool(tool.name, tool.description, tool.schema, tool.handler); });