TIDAL MCP Server

Instructions

Implementation Reference

• src/tidal_mcp/server.py:687-737 (handler)

  The main execution logic for the 'update_playlist' tool. Fetches the playlist using tidalapi.session.playlist, edits name/description via playlist.edit, refreshes the object, and returns structured UpdatePlaylistResult.

  @mcp.tool()
  async def update_playlist(
      playlist_id: str, name: Optional[str] = None, description: Optional[str] = None
  ) -> UpdatePlaylistResult:
      """
      Update a playlist's name and/or description.
  
      Args:
          playlist_id: ID of the playlist to update
          name: New name for the playlist (optional)
          description: New description (optional)
  
      Returns:
          Updated playlist details
      """
      if not await ensure_authenticated():
          raise ToolError("Not authenticated. Please run the 'login' tool first.")
  
      if not name and description is None:
          raise ToolError("Must provide at least name or description to update")
  
      try:
          playlist = await anyio.to_thread.run_sync(session.playlist, playlist_id)
          if not playlist:
              raise ToolError(f"Playlist with ID '{playlist_id}' not found")
  
          # Update the playlist
          if name:
              await anyio.to_thread.run_sync(playlist.edit, name, description)
          elif description is not None:
              await anyio.to_thread.run_sync(playlist.edit, playlist.name, description)
  
          # Fetch updated playlist
          updated_playlist = await anyio.to_thread.run_sync(session.playlist, playlist_id)
  
          return UpdatePlaylistResult(
              status="success",
              playlist=Playlist(
                  id=str(updated_playlist.id),
                  name=updated_playlist.name,
                  description=updated_playlist.description or "",
                  track_count=getattr(updated_playlist, "num_tracks", 0),
                  creator=None,
                  url=f"https://tidal.com/browse/playlist/{playlist_id}",
              ),
              message=f"Updated playlist '{updated_playlist.name}'",
          )
      except ToolError:
          raise
      except Exception as e:
          raise ToolError(f"Failed to update playlist: {str(e)}")

• src/tidal_mcp/models.py:160-166 (schema)

  Pydantic output schema model used by the update_playlist handler for structured responses.

  class UpdatePlaylistResult(BaseModel):
      """Result of updating a playlist."""
  
      status: str = Field(description="Operation status (success/error)")
      playlist: Optional[Playlist] = Field(None, description="Updated playlist details")
      message: str = Field(description="Status message")

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

  FastMCP @mcp.tool() decorator registers the update_playlist function as an MCP tool.

  @mcp.tool()

• src/tidal_mcp/models.py:47-56 (schema)

  Shared Pydantic model for playlist entities, embedded in UpdatePlaylistResult.

  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")