TIDAL MCP Server

Instructions

Implementation Reference

• src/tidal_mcp/server.py:593-630 (handler)

  The core handler function for the 'add_tracks_to_playlist' tool. Decorated with @mcp.tool() for automatic registration in FastMCP. Implements authentication check, playlist fetching, track ID conversion, addition via tidalapi.Playlist.add(), and structured result return.

  @mcp.tool()
  async def add_tracks_to_playlist(playlist_id: str, track_ids: List[str]) -> AddTracksResult:
      """
      Add tracks to an existing playlist.
  
      Args:
          playlist_id: ID of the playlist
          track_ids: List of track IDs to add
  
      Returns:
          Success status and number of tracks added
      """
      if not await ensure_authenticated():
          raise ToolError("Not authenticated. Please run the 'login' tool first.")
  
      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")
  
          track_ids_int = [int(tid) for tid in track_ids]
          await anyio.to_thread.run_sync(playlist.add, track_ids_int)
  
          return AddTracksResult(
              status="success",
              playlist_id=playlist_id,
              playlist_name=playlist.name,
              tracks_added=len(track_ids),
              playlist_url=f"https://tidal.com/browse/playlist/{playlist_id}",
              message=f"Added {len(track_ids)} tracks to playlist '{playlist.name}'",
          )
      except ValueError as e:
          raise ToolError(f"Invalid track ID format: {str(e)}")
      except ToolError:
          raise
      except Exception as e:
          raise ToolError(f"Failed to add tracks: {str(e)}")

• src/tidal_mcp/models.py:139-148 (schema)

  Pydantic model defining the structured output schema for the add_tracks_to_playlist tool response, ensuring type-safe JSON serialization with descriptive fields.

  class AddTracksResult(BaseModel):
      """Result of adding tracks to a playlist."""
  
      status: str = Field(description="Operation status (success/error)")
      playlist_id: str = Field(description="ID of the playlist")
      playlist_name: str = Field(description="Name of the playlist")
      tracks_added: int = Field(description="Number of tracks successfully added")
      playlist_url: str = Field(description="TIDAL web URL for the playlist")
      message: str = Field(description="Status message")