TIDAL MCP Server

Instructions

Implementation Reference

• src/tidal_mcp/server.py:1332-1384 (handler)

  The main handler function implementing get_similar_albums tool. Fetches the seed album via session.album, retrieves similar albums using album.similar(), limits the results, maps to Album models, and returns AlbumList.

  @mcp.tool()
  async def get_similar_albums(album_id: str, limit: int = 10) -> AlbumList:
      """
      Get albums similar to the specified album.
  
      Args:
          album_id: ID of the seed album
          limit: Maximum albums to return (default: 10, max: 50)
  
      Returns:
          List of similar albums
      """
      if not await ensure_authenticated():
          raise ToolError("Not authenticated. Please run the 'login' tool first.")
  
      try:
          limit = min(max(1, limit), 50)
  
          album = await anyio.to_thread.run_sync(session.album, album_id)
          if not album:
              raise ToolError(f"Album with ID '{album_id}' not found")
  
          similar = await anyio.to_thread.run_sync(album.similar)
          limited_similar = similar[:limit] if similar else []
  
          albums = []
          for a in limited_similar:
              release_date = None
              if hasattr(a, "release_date") and a.release_date:
                  release_date = str(a.release_date)
  
              albums.append(
                  Album(
                      id=str(a.id),
                      title=a.name,
                      artist=a.artist.name if a.artist else "Unknown Artist",
                      release_date=release_date,
                      num_tracks=getattr(a, "num_tracks", 0),
                      duration_seconds=getattr(a, "duration", 0),
                      url=f"https://tidal.com/browse/album/{a.id}",
                  )
              )
  
          return AlbumList(
              status="success",
              count=len(albums),
              albums=albums,
          )
      except ToolError:
          raise
      except Exception as e:
          raise ToolError(f"Failed to get similar albums: {str(e)}")

• src/tidal_mcp/models.py:71-78 (schema)

  Pydantic BaseModel defining the structured output schema AlbumList returned by the get_similar_albums tool.

  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 BaseModel defining the Album entity used within the AlbumList output schema.

  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:87-87 (registration)

  Tool description in server instructions, indicating registration and purpose.

  - get_similar_albums: Find albums similar to a given album