MCP Claude Spotify

Instructions

Implementation Reference

• index.ts:1305-1348 (handler)

  Handler for 'get-recommendations' tool: parses arguments with Zod schema, validates seeds, builds query params for Spotify /recommendations endpoint, fetches data via spotifyApiRequest, formats track list response.

        if (name === "get-recommendations") {
          const { seedTracks, seedArtists, seedGenres, limit } = GetRecommendationsSchema.parse(args);
          
          if (!seedTracks && !seedArtists && !seedGenres) {
            throw new Error("At least one seed (tracks, artists, or genres) must be provided");
          }
          
          const params = new URLSearchParams();
          
          if (limit) params.append("limit", limit.toString());
          if (seedTracks) params.append("seed_tracks", seedTracks.join(","));
          if (seedArtists) params.append("seed_artists", seedArtists.join(","));
          if (seedGenres) params.append("seed_genres", seedGenres.join(","));
          
          const recommendations = await spotifyApiRequest(`/recommendations?${params}`);
          
          const formattedRecommendations = recommendations.tracks
            .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");
          
          return {
            content: [
              {
                type: "text",
                text: recommendations.tracks.length > 0
                  ? `Recommended tracks:\n${formattedRecommendations}`
                  : "No recommendations found.",
              },
            ],
          };
        }

• index.ts:193-198 (schema)

  Zod schema for validating input parameters to get-recommendations tool: seedTracks, seedArtists, seedGenres (arrays of strings, optional), limit (number 1-100, default 20). Used in handler for parsing.

  const GetRecommendationsSchema = z.object({
    seedTracks: z.array(z.string()).optional(),
    seedArtists: z.array(z.string()).optional(),
    seedGenres: z.array(z.string()).optional(),
    limit: z.number().min(1).max(100).default(20),
  });

• index.ts:772-805 (registration)

  Tool registration in ListTools response: defines name, description, and inputSchema matching the Zod schema for get-recommendations.

  {
    name: "get-recommendations",
    description: "Get track recommendations based on seeds",
    inputSchema: {
      type: "object",
      properties: {
        seedTracks: {
          type: "array",
          items: {
            type: "string",
          },
          description: "Array of Spotify track IDs to use as seeds (optional)",
        },
        seedArtists: {
          type: "array",
          items: {
            type: "string",
          },
          description: "Array of Spotify artist IDs to use as seeds (optional)",
        },
        seedGenres: {
          type: "array",
          items: {
            type: "string",
          },
          description: "Array of genre names to use as seeds (optional)",
        },
        limit: {
          type: "number",
          description: "Maximum number of tracks to return (1-100, default: 20)",
        },
      },
    },
  },