TIDAL MCP Server

Instructions

Implementation Reference

• src/tidal_mcp/server.py:1291-1329 (handler)

  The handler function for the 'get_album' tool. It checks authentication, fetches the album using tidalapi session.album, extracts details, constructs an AlbumDetails object, and returns it. Registered via @mcp.tool() decorator.

  @mcp.tool()
  async def get_album(album_id: str) -> AlbumDetails:
      """
      Get detailed information about an album.
  
      Args:
          album_id: ID of the album
  
      Returns:
          Album details including title, artist, release date, and track count
      """
      if not await ensure_authenticated():
          raise ToolError("Not authenticated. Please run the 'login' tool first.")
  
      try:
          album = await anyio.to_thread.run_sync(session.album, album_id)
          if not album:
              raise ToolError(f"Album with ID '{album_id}' not found")
  
          release_date = None
          if hasattr(album, "release_date") and album.release_date:
              release_date = str(album.release_date)
  
          return AlbumDetails(
              status="success",
              album=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}",
              ),
          )
      except ToolError:
          raise
      except Exception as e:
          raise ToolError(f"Failed to get album: {str(e)}")

• src/tidal_mcp/models.py:202-207 (schema)

  Pydantic model defining the output schema for the get_album tool response.

  class AlbumDetails(BaseModel):
      """Detailed album information."""
  
      status: str = Field(description="Operation status (success/error)")
      album: Album = Field(description="Album information")

• src/tidal_mcp/models.py:27-37 (schema)

  Pydantic model used within AlbumDetails for the structured album data in get_album 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:120-151 (helper)

  Helper function used by get_album to ensure the user is authenticated before fetching album data.

  async def ensure_authenticated() -> bool:
      """
      Check if user is authenticated with TIDAL.
      Automatically loads persisted session if available.
      """
      if await anyio.Path(SESSION_FILE).exists():
          try:
              async with await anyio.open_file(SESSION_FILE, "r") as f:
                  content = await f.read()
                  data = json.loads(content)
  
              # Load OAuth session
              result = await anyio.to_thread.run_sync(
                  session.load_oauth_session,
                  data["token_type"]["data"],
                  data["access_token"]["data"],
                  data["refresh_token"]["data"],
                  None,  # expiry time
              )
  
              if result:
                  is_valid = await anyio.to_thread.run_sync(session.check_login)
                  if not is_valid:
                      await anyio.Path(SESSION_FILE).unlink()
                  return is_valid
              return False
          except Exception:
              await anyio.Path(SESSION_FILE).unlink()
              return False
  
      return await anyio.to_thread.run_sync(session.check_login)