search_playlists
Find public TIDAL playlists by name or theme to discover curated music collections for any mood or activity.
Instructions
Search for public playlists on TIDAL.
Args: query: Search query - playlist name or theme limit: Maximum results (1-50, default: 10)
Returns: List of matching playlists with id, name, description, track count, and URL
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| limit | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| count | Yes | Number of playlists returned | |
| query | No | Search query used (for search results) | |
| status | Yes | Operation status (success/error) | |
| playlists | Yes | List of playlist objects |
Implementation Reference
- src/tidal_mcp/server.py:352-392 (handler)The core handler function implementing the search_playlists tool. It checks authentication, performs a search using tidalapi.session.search for Playlists, processes results into Playlist objects, and returns a structured PlaylistList response.
@mcp.tool() async def search_playlists(query: str, limit: int = 10) -> PlaylistList: """ Search for public playlists on TIDAL. Args: query: Search query - playlist name or theme limit: Maximum results (1-50, default: 10) Returns: List of matching playlists with id, name, description, track count, and URL """ if not await ensure_authenticated(): raise ToolError("Not authenticated. Please run the 'login' tool first.") try: limit = min(max(1, limit), 50) results = await anyio.to_thread.run_sync( lambda: session.search(query, models=[tidalapi.Playlist], limit=limit) ) playlists = [] for playlist in results.get("playlists", []): creator_name = None if hasattr(playlist, "creator") and playlist.creator: creator_name = getattr(playlist.creator, "name", None) playlists.append( Playlist( id=str(playlist.id), name=playlist.name, description=getattr(playlist, "description", "") or "", track_count=getattr(playlist, "num_tracks", 0), creator=creator_name, url=f"https://tidal.com/browse/playlist/{playlist.id}", ) ) return PlaylistList(status="success", query=query, count=len(playlists), playlists=playlists) except Exception as e: raise ToolError(f"Playlist search failed: {str(e)}") - src/tidal_mcp/models.py:89-96 (schema)Pydantic model defining the output schema returned by the search_playlists tool handler.
class PlaylistList(BaseModel): """List of playlists with metadata.""" status: str = Field(description="Operation status (success/error)") query: Optional[str] = Field(None, description="Search query used (for search results)") count: int = Field(description="Number of playlists returned") playlists: List[Playlist] = Field(description="List of playlist objects") - src/tidal_mcp/models.py:47-56 (schema)Pydantic model for the individual Playlist entities composing the output list of the search_playlists tool.
class Playlist(BaseModel): """Structured representation of a TIDAL playlist.""" id: str = Field(description="Unique playlist ID (UUID)") name: str = Field(description="Playlist name") description: str = Field(description="Playlist description") track_count: int = Field(description="Number of tracks in playlist") creator: Optional[str] = Field(None, description="Playlist creator name") url: str = Field(description="TIDAL web URL for the playlist") - src/tidal_mcp/server.py:65-65 (registration)Tool description listed in server instructions for discovery and usage guidance.
- search_playlists: Find public playlists