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}`); } } }