Spotify MCP Server

Instructions

Implementation Reference

• src/spotify.ts:383-399 (handler)

  The primary handler function in SpotifyService that executes the tool logic by querying the Spotify API for an artist's albums, handling album types (album, single, appears_on, compilation) and pagination limits.
  async getArtistAlbums( token: string, artistId: string, albumType: "album" | "single" | "appears_on" | "compilation" = "album", limit: number = 20 ): Promise<PagingObject<SpotifyAlbum>> { const id = this.extractId(artistId); const params = { include_groups: albumType, limit: Math.min(limit, 50), }; return await this.makeRequest<PagingObject<SpotifyAlbum>>( `artists/${id}/albums`, token, params ); }
• src/mcp/tools/artists.ts:47-95 (registration)

  Registers the 'get_artist_albums' tool in the artistTools object, including title, detailed description, input schema, and a delegating handler that calls SpotifyService.getArtistAlbums.
  get_artist_albums: { title: "Get Artist Albums", description: `Explore an artist's complete discography including albums, singles, compilations, and appearances. 🎯 USE CASES: • Building complete artist discography playlists • Discovering rare releases and B-sides • Tracking artist evolution through their album releases • Finding collaborations and featured appearances • Creating chronological listening experiences 📝 WHAT IT RETURNS: • Complete album listing with release dates and types • Album artwork and track counts • Collaboration information and featured artists • Market availability and release formats • Popularity metrics for each release 🔍 EXAMPLES: • "Get all albums by The Beatles" • "Show me Drake's singles and EPs only" • "Find all releases by artist ID: 4dpARuHxo51G3z768sgnrY" • "I want to see Beyoncé's complete discography" 💡 ALBUM TYPES: • 'album' - Full studio albums • 'single' - Singles and EPs • 'compilation' - Greatest hits, compilations • 'appears_on' - Featured appearances on other artists' work ⚠️ REQUIREMENTS: • Valid Spotify access token • Artist must have releases available`, schema: createSchema({ token: commonSchemas.token(), artistId: commonSchemas.spotifyId("artist"), albumType: commonSchemas.albumType(), limit: commonSchemas.limit(1, 50, 20), }), handler: async (args: any, spotifyService: SpotifyService) => { const { token, artistId, albumType = "album", limit = 20 } = args; return await spotifyService.getArtistAlbums( token, artistId, albumType, limit ); }, },
• src/mcp/tools/artists.ts:80-85 (schema)

  Input schema definition for the tool, validating token, artist ID, optional album type, and limit using shared common schemas.
  schema: createSchema({ token: commonSchemas.token(), artistId: commonSchemas.spotifyId("artist"), albumType: commonSchemas.albumType(), limit: commonSchemas.limit(1, 50, 20), }),
• src/mcp/tools/index.ts:4-25 (registration)

  Top-level registration where artistTools (containing get_artist_albums) is imported and spread into the allTools registry used by ToolRegistrar for MCP tool exposure.
  import { artistTools } from "./artists"; import { trackTools } from "./tracks"; import { playlistTools } from "./playlists"; import { playbackTools } from "./playback"; import { userTools } from "./user"; import { searchTools } from "./search"; export interface ToolDefinition { title: string; description: string; schema: z.ZodObject<any>; handler: (args: any, spotifyService: SpotifyService) => Promise<any>; } export interface ToolsRegistry { [key: string]: ToolDefinition; } export const allTools: ToolsRegistry = { ...albumTools, ...artistTools,