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 that executes the searchSpotify tool logic. It uses handleSpotifyRequest to call spotifyApi.search with the provided query, type, and limit, then formats the results into a markdown text response based on the type (track, album, artist, playlist).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:23-36 (schema)Zod input schema definition for the searchSpotify tool, validating query (string), type (enum: track/album/artist/playlist), and optional limit (1-50).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/index.ts:12-14 (registration)Registration of all tools, including searchSpotify (via readTools), to the MCP server using server.tool().[...readTools, ...playTools, ...albumTools].forEach((tool) => { server.tool(tool.name, tool.description, tool.schema, tool.handler); });
- src/read.ts:603-612 (registration)Export of readTools array that includes the searchSpotify tool object, which is later imported and registered in index.ts.export const readTools = [ searchSpotify, getNowPlaying, getMyPlaylists, getPlaylistTracks, getRecentlyPlayed, getUsersSavedTracks, getQueue, getAvailableDevices, ];