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

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
```

TIDAL MCP Server