MCP Claude Spotify

Instructions

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"],
    },
  },