Spotify MCP Server

Instructions

Implementation Reference

• src/mcp/tools/tracks.ts:50-102 (registration)

  Defines the 'search_tracks' MCP tool including title, description, input schema, and handler function that delegates to SpotifyService.searchTracks

    search_tracks: {
      title: "Search Tracks",
      description: `Search specifically for individual tracks with targeted filtering for precise song discovery.
  
  🎯 USE CASES:
  • Find specific songs when you remember lyrics or melodies
  • Discover tracks by particular artists or from specific albums
  • Build track-focused music discovery experiences
  • Find alternative versions, covers, or remixes of songs
  • Research song catalogs and discographies
  
  📝 WHAT IT RETURNS:
  • Ranked track results based on search relevance
  • Song titles, artists, albums, and release information
  • Track popularity scores and listener engagement
  • Preview URLs for instant track sampling
  • Market availability and explicit content flags
  
  🔍 EXAMPLES:
  • "Search for tracks with 'love' in the title"
  • "Find acoustic versions of popular songs"
  • "Look for instrumental jazz piano tracks"
  • "Search for covers of 'Yesterday' by The Beatles"
  
  🎵 SEARCH PRECISION:
  • Track-specific results without album/artist clutter
  • Optimized for individual song discovery
  • Better for finding specific recordings or versions
  • Perfect for playlist building and curation
  • Ideal for karaoke or cover song searches
  
  💡 SEARCH STRATEGIES:
  • Include specific lyrics: "lyrics hello darkness my old friend"
  • Search by genre: "indie folk acoustic guitar"
  • Find versions: "acoustic", "remix", "live", "cover"
  • Use artist filters: "artist:Taylor Swift love songs"
  • Include year ranges: "track:dancing year:2020-2023"
  
  ⚠️ REQUIREMENTS:
  • Valid Spotify access token
  • Search terms should be specific for best results`,
      schema: createSchema({
        token: commonSchemas.token(),
        query: commonSchemas.searchQuery(
          "tracks (song title, artist, album, keywords)"
        ),
        limit: commonSchemas.limit(1, 50, 20),
      }),
      handler: async (args: any, spotifyService: SpotifyService) => {
        const { token, query, limit = 20 } = args;
        return await spotifyService.searchTracks(token, query, limit);
      },
    },

• src/spotify.ts:466-477 (handler)

  Core implementation of track search using Spotify's search API endpoint, limited to tracks (type='track')

  async searchTracks(
    token: string,
    query: string,
    limit: number = 20
  ): Promise<SearchResult> {
    const params = {
      q: query,
      type: "track",
      limit: Math.min(limit, 50),
    };
    return await this.makeRequest<SearchResult>("search", token, params);
  }

• src/mcp/tools/index.ts:22-36 (registration)

  Registers trackTools (including search_tracks) into the central allTools registry used by ToolRegistrar

  export const allTools: ToolsRegistry = {
    ...albumTools,
  
    ...artistTools,
  
    ...trackTools,
  
    ...playlistTools,
  
    ...playbackTools,
  
    ...userTools,
  
    ...searchTools,
  };

• src/mcp/tools/tracks.ts:91-97 (schema)

  Zod-based input schema for search_tracks tool defining token, query, and limit parameters

  schema: createSchema({
    token: commonSchemas.token(),
    query: commonSchemas.searchQuery(
      "tracks (song title, artist, album, keywords)"
    ),
    limit: commonSchemas.limit(1, 50, 20),
  }),

• src/spotify.ts:237-272 (helper)

  Generic HTTP request helper used by searchTracks to make authenticated API calls to Spotify

  private async makeRequest<T = any>(
    endpoint: string,
    token: string,
    params: Record<string, any> = {},
    method: "GET" | "POST" | "PUT" | "DELETE" = "GET",
    data: any = null
  ): Promise<T> {
    try {
      const url = endpoint.startsWith("http")
        ? endpoint
        : `${this.baseURL}/${endpoint}`;
  
      const config = {
        method,
        url,
        headers: this.getAuthHeaders(token),
        params: method === "GET" ? params : undefined,
        data: method !== "GET" ? data : undefined,
      };
  
      const response: AxiosResponse<T> = await axios(config);
      return response.data;
    } catch (error: any) {
      if (error.response) {
        const errorMessage =
          error.response.data?.error?.message || error.response.statusText;
        throw new Error(
          `Spotify API Error: ${error.response.status} - ${errorMessage}`
        );
      } else if (error.request) {
        throw new Error("Unable to connect to Spotify API");
      } else {
        throw new Error(`Request error: ${error.message}`);
      }
    }
  }