TIDAL MCP Server

Instructions

Implementation Reference

• src/tidal_mcp/server.py:951-989 (handler)

  The handler function for the 'get_artist' tool. It authenticates if needed, fetches the artist object using tidalapi, attempts to retrieve the biography, constructs an ArtistDetails object, and returns it. Registered via @mcp.tool() decorator.

  @mcp.tool()
  async def get_artist(artist_id: str) -> ArtistDetails:
      """
      Get detailed information about an artist including biography.
  
      Args:
          artist_id: ID of the artist
  
      Returns:
          Artist details including name, URL, and biography
      """
      if not await ensure_authenticated():
          raise ToolError("Not authenticated. Please run the 'login' tool first.")
  
      try:
          artist = await anyio.to_thread.run_sync(session.artist, artist_id)
          if not artist:
              raise ToolError(f"Artist with ID '{artist_id}' not found")
  
          # Try to get biography
          bio = None
          try:
              bio = await anyio.to_thread.run_sync(artist.get_bio)
          except Exception:
              pass  # Bio may not be available for all artists
  
          return ArtistDetails(
              status="success",
              artist=Artist(
                  id=str(artist.id),
                  name=artist.name,
                  url=f"https://tidal.com/browse/artist/{artist.id}",
              ),
              bio=bio,
          )
      except ToolError:
          raise
      except Exception as e:
          raise ToolError(f"Failed to get artist: {str(e)}")

• src/tidal_mcp/models.py:194-200 (schema)

  Pydantic model defining the output schema for the get_artist tool response, including status, nested Artist object, and optional biography.

  class ArtistDetails(BaseModel):
      """Detailed artist information including biography."""
  
      status: str = Field(description="Operation status (success/error)")
      artist: Artist = Field(description="Artist basic information")
      bio: Optional[str] = Field(None, description="Artist biography text")

• src/tidal_mcp/models.py:39-45 (schema)

  Pydantic model for the Artist entity used within ArtistDetails schema.

  class Artist(BaseModel):
      """Structured representation of a TIDAL artist."""
  
      id: str = Field(description="Unique TIDAL artist ID")
      name: str = Field(description="Artist name")
      url: str = Field(description="TIDAL web URL for the artist")

• src/tidal_mcp/server.py:101-104 (registration)

  Initialization of the FastMCP server instance where all @mcp.tool() decorated functions are automatically registered as MCP tools.

  mcp = FastMCP(
      name=SERVER_NAME,
      instructions=SERVER_INSTRUCTIONS,
  )

• src/tidal_mcp/server.py:120-151 (helper)

  Shared helper function used by get_artist (and all tools) to ensure authentication before API calls.

  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)