get_favorite_albums
Retrieve a user's saved albums from TIDAL music streaming service. Specify a limit to control how many albums are returned.
Instructions
Get user's favorite (saved) albums from TIDAL.
Args: limit: Maximum albums to retrieve (default: 50)
Returns: List of favorite albums
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| count | Yes | Number of albums returned | |
| query | No | Search query used (for search results) | |
| albums | Yes | List of album objects | |
| status | Yes | Operation status (success/error) |
Implementation Reference
- src/tidal_mcp/server.py:1147-1187 (handler)Core handler function for the get_favorite_albums tool. Fetches user's saved albums using tidalapi.session.user.favorites.albums(), transforms them into Album models, and returns an AlbumList.
@mcp.tool() async def get_favorite_albums(limit: int = 50) -> AlbumList: """ Get user's favorite (saved) albums from TIDAL. Args: limit: Maximum albums to retrieve (default: 50) Returns: List of favorite albums """ if not await ensure_authenticated(): raise ToolError("Not authenticated. Please run the 'login' tool first.") try: favorites = await anyio.to_thread.run_sync( lambda: session.user.favorites.albums(limit=limit) ) albums = [] for album in favorites: release_date = None if hasattr(album, "release_date") and album.release_date: release_date = str(album.release_date) albums.append( Album( id=str(album.id), title=album.name, artist=album.artist.name if album.artist else "Unknown Artist", release_date=release_date, num_tracks=getattr(album, "num_tracks", 0), duration_seconds=getattr(album, "duration", 0), url=f"https://tidal.com/browse/album/{album.id}", ) ) return AlbumList(status="success", count=len(albums), albums=albums) except Exception as e: raise ToolError(f"Failed to get favorite albums: {str(e)}") - src/tidal_mcp/models.py:71-78 (schema)Pydantic schema for the AlbumList return type of get_favorite_albums.
class AlbumList(BaseModel): """List of albums 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 albums returned") albums: List[Album] = Field(description="List of album objects") - src/tidal_mcp/models.py:27-37 (schema)Pydantic schema for individual Album objects contained in the AlbumList response.
class Album(BaseModel): """Structured representation of a TIDAL album.""" id: str = Field(description="Unique TIDAL album ID") title: str = Field(description="Album title") artist: str = Field(description="Primary artist name") release_date: Optional[str] = Field(None, description="Release date (YYYY-MM-DD)") num_tracks: int = Field(description="Number of tracks in album") duration_seconds: int = Field(description="Total album duration in seconds") url: str = Field(description="TIDAL web URL for the album") - src/tidal_mcp/server.py:1147-1147 (registration)FastMCP decorator that registers the get_favorite_albums function as a tool.
@mcp.tool()