Spotify Playlist MCP Server

Instructions

Implementation Reference

• server.py:450-534 (handler)

  The async handler function that implements the spotify_search_tracks tool. It takes SearchTracksInput, calls Spotify's search API, formats results as markdown list or JSON, handles pagination, truncation, and errors.
  async def spotify_search_tracks(params: SearchTracksInput) -> str: """Search for tracks on Spotify by name, artist, album, or keywords. Searches Spotify's entire catalog using intelligent matching. Results ranked by relevance. Args: - query: Search text, 1-200 chars (e.g., "Bohemian Rhapsody", "artist:Queen", "album:...", or keywords) - limit: Results to return, 1-50 (default: 20) - offset: Starting position for pagination (default: 0) - response_format: 'markdown' or 'json' Returns: Markdown: Search results with track details (name, artists, album, duration, ID, URI, popularity) JSON: {"total": N, "count": N, "offset": N, "tracks": [{id, name, artists, album, duration_ms, popularity, uri, external_urls}], "has_more": bool} Examples: - "Find Bohemian Rhapsody by Queen" -> query="Bohemian Rhapsody Queen" - "Search for songs by Taylor Swift" -> query="artist:Taylor Swift" - "Look for indie rock songs" -> query="indie rock" Errors: Returns "No tracks found" if no results, or error for auth failure (401), rate limits (429). Truncates if exceeds character limit. """ try: query_params = { "q": params.query, "type": "track", "limit": params.limit, "offset": params.offset, } data = await make_spotify_request("search", params=query_params) tracks = data.get("tracks", {}).get("items", []) total = data.get("tracks", {}).get("total", 0) if not tracks: return f"No tracks found matching '{params.query}'" # Format response if params.response_format == ResponseFormat.MARKDOWN: lines = [ f"# Search Results: '{params.query}'\n", f"Found {total} tracks (showing {len(tracks)})\n", ] for i, track in enumerate(tracks, 1): lines.append(f"## {i}. {format_track_markdown(track)}\n") has_more = total > params.offset + len(tracks) if has_more: next_offset = params.offset + len(tracks) lines.append( f"\n*More results available. Use offset={next_offset} to see more.*" ) result = "\n".join(lines) truncation_msg = check_character_limit(result, tracks) if truncation_msg: tracks = tracks[: len(tracks) // 2] lines = [ f"# Search Results: '{params.query}'\n", truncation_msg, f"Found {total} tracks (showing {len(tracks)})\n", ] for i, track in enumerate(tracks, 1): lines.append(f"## {i}. {format_track_markdown(track)}\n") result = "\n".join(lines) return result else: # JSON format return json.dumps( { "total": total, "count": len(tracks), "offset": params.offset, "tracks": tracks, "has_more": total > params.offset + len(tracks), }, indent=2, ) except Exception as e: return handle_spotify_error(e)
• server.py:440-449 (registration)

  The @mcp.tool decorator that registers the spotify_search_tracks function as an MCP tool with appropriate annotations.
  @mcp.tool( name="spotify_search_tracks", annotations={ "title": "Search Spotify Tracks", "readOnlyHint": True, "destructiveHint": False, "idempotentHint": True, "openWorldHint": True, }, )
• spotify_mcp/types.py:174-190 (schema)

  Pydantic BaseModel defining the input schema for the tool, including query (required, 1-200 chars), optional limit (1-50), offset (>=0), and response_format.
  class SearchTracksInput(BaseModel): """Input model for searching tracks.""" model_config = ConfigDict(str_strip_whitespace=True, validate_assignment=True) query: str = Field( ..., description="Search query for tracks", min_length=1, max_length=200 ) limit: int | None = Field( default=20, description="Number of results to return", ge=1, le=50 ) offset: int | None = Field(default=0, description="Offset for pagination", ge=0) response_format: ResponseFormat = Field( default=ResponseFormat.MARKDOWN, description="Output format: 'markdown' or 'json'", )