searchSpotify
Search for tracks, albums, artists, or playlists on Spotify to find specific music content using queries and filters.
Instructions
Search for tracks, albums, artists, or playlists on Spotify
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The search query | |
| type | Yes | The type of item to search for either track, album, artist, or playlist | |
| limit | No | Maximum number of results to return (10-50) |
Implementation Reference
- src/read.ts:37-111 (handler)The handler function for the searchSpotify tool. Performs Spotify API search based on query, type (track/album/artist/playlist), and limit. Formats and returns results as markdown text or handles errors.handler: async (args, _extra: SpotifyHandlerExtra) => { const { query, type, limit } = args; const limitValue = limit ?? 10; try { const results = await handleSpotifyRequest(async (spotifyApi) => { return await spotifyApi.search( query, [type], undefined, limitValue as MaxInt<50>, ); }); let formattedResults = ''; if (type === 'track' && results.tracks) { formattedResults = results.tracks.items .map((track, i) => { const artists = track.artists.map((a) => a.name).join(', '); const duration = formatDuration(track.duration_ms); return `${i + 1}. "${ track.name }" by ${artists} (${duration}) - ID: ${track.id}`; }) .join('\n'); } else if (type === 'album' && results.albums) { formattedResults = results.albums.items .map((album, i) => { const artists = album.artists.map((a) => a.name).join(', '); return `${i + 1}. "${album.name}" by ${artists} - ID: ${album.id}`; }) .join('\n'); } else if (type === 'artist' && results.artists) { formattedResults = results.artists.items .map((artist, i) => { return `${i + 1}. ${artist.name} - ID: ${artist.id}`; }) .join('\n'); } else if (type === 'playlist' && results.playlists) { formattedResults = results.playlists.items .map((playlist, i) => { return `${i + 1}. "${playlist?.name ?? 'Unknown Playlist'} (${ playlist?.description ?? 'No description' } tracks)" by ${playlist?.owner?.display_name} - ID: ${ playlist?.id }`; }) .join('\n'); } return { content: [ { type: 'text', text: formattedResults.length > 0 ? `# Search results for "${query}" (type: ${type})\n\n${formattedResults}` : `No ${type} results found for "${query}"`, }, ], }; } catch (error) { return { content: [ { type: 'text', text: `Error searching for ${type}s: ${ error instanceof Error ? error.message : String(error) }`, }, ], }; } },
- src/read.ts:21-36 (schema)Name, description, and Zod input schema definition for the searchSpotify tool.name: 'searchSpotify', description: 'Search for tracks, albums, artists, or playlists on Spotify', schema: { query: z.string().describe('The search query'), type: z .enum(['track', 'album', 'artist', 'playlist']) .describe( 'The type of item to search for either track, album, artist, or playlist', ), limit: z .number() .min(1) .max(50) .optional() .describe('Maximum number of results to return (10-50)'), },
- src/read.ts:531-539 (registration)The searchSpotify tool is registered in the readTools array alongside other read operations.export const readTools = [ searchSpotify, getNowPlaying, getMyPlaylists, getPlaylistTracks, getRecentlyPlayed, getUsersSavedTracks, getQueue, ];
- src/index.ts:12-14 (registration)The MCP server registers all tools (including searchSpotify via readTools) by calling server.tool for each.[...readTools, ...playTools, ...albumTools].forEach((tool) => { server.tool(tool.name, tool.description, tool.schema, tool.handler); });