search-spotify
Search Spotify for tracks, albums, artists, or playlists by specifying a query and item type. Retrieve up to 50 results, ideal for finding music content quickly.
Instructions
Search for tracks, albums, artists, or playlists on Spotify
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results to return (1-50, default: 10) | |
| query | Yes | Search query | |
| type | No | Type of item to search for (default: track) |
Implementation Reference
- index.ts:997-1077 (handler)Handler for 'search-spotify' tool: validates input with SearchSchema, calls Spotify /search API, formats and returns search results for tracks, albums, artists, or playlists.if (name === "search-spotify") { const { query, type, limit } = SearchSchema.parse(args); const results = await spotifyApiRequest( `/search?${querystring.stringify({ q: query, type, limit, })}` ); let formattedResults = ""; if (type === "track" && results.tracks) { formattedResults = results.tracks.items .map( (track: any) => ` Track: ${track.name} Artist: ${track.artists.map((a: any) => a.name).join(", ")} Album: ${track.album.name} ID: ${track.id} Duration: ${Math.floor(track.duration_ms / 1000 / 60)}:${( Math.floor(track.duration_ms / 1000) % 60 ) .toString() .padStart(2, "0")} URL: ${track.external_urls.spotify} ---` ) .join("\n"); } else if (type === "album" && results.albums) { formattedResults = results.albums.items .map( (album: any) => ` Album: ${album.name} Artist: ${album.artists.map((a: any) => a.name).join(", ")} ID: ${album.id} Release Date: ${album.release_date} Tracks: ${album.total_tracks} URL: ${album.external_urls.spotify} ---` ) .join("\n"); } else if (type === "artist" && results.artists) { formattedResults = results.artists.items .map( (artist: any) => ` Artist: ${artist.name} ID: ${artist.id} Popularity: ${artist.popularity}/100 Followers: ${artist.followers?.total || "N/A"} Genres: ${artist.genres?.join(", ") || "None"} URL: ${artist.external_urls.spotify} ---` ) .join("\n"); } else if (type === "playlist" && results.playlists) { formattedResults = results.playlists.items .map( (playlist: any) => ` Playlist: ${playlist.name} Creator: ${playlist.owner.display_name} ID: ${playlist.id} Tracks: ${playlist.tracks.total} Description: ${playlist.description || "None"} URL: ${playlist.external_urls.spotify} ---` ) .join("\n"); } return { content: [ { type: "text", text: formattedResults || `No ${type}s found matching your search.`, }, ], };
- index.ts:171-175 (schema)Zod schema for validating input parameters of search-spotify tool: query (required), type (default track), limit (1-50, default 10). Used in handler.const SearchSchema = z.object({ query: z.string(), type: z.enum(["track", "album", "artist", "playlist"]).default("track"), limit: z.number().min(1).max(50).default(10), });
- index.ts:639-661 (registration)Tool registration in ListTools response: defines name, description, and MCP inputSchema matching the zod SearchSchema.{ name: "search-spotify", description: "Search for tracks, albums, artists, or playlists on Spotify", inputSchema: { type: "object", properties: { query: { type: "string", description: "Search query", }, type: { type: "string", enum: ["track", "album", "artist", "playlist"], description: "Type of item to search for (default: track)", }, limit: { type: "number", description: "Maximum number of results to return (1-50, default: 10)", }, }, required: ["query"], }, },