Spotify MCP Server

Instructions

Implementation Reference

• src/spotify_mcp/server.py:445-526 (handler)

  Main handler for SpotifyPlaylist tool calls, handling actions: get, get_tracks, add_tracks, remove_tracks, change_details by delegating to spotify_client.

  case "Playlist":
      logger.info(f"Playlist operation with arguments: {arguments}")
      action = arguments.get("action")
      match action:
          case "get":
              logger.info(f"Getting current user's playlists with arguments: {arguments}")
              playlists = spotify_client.get_current_user_playlists()
              return [types.TextContent(
                  type="text",
                  text=json.dumps(playlists, indent=2)
              )]
          case "get_tracks":
              logger.info(f"Getting tracks in playlist with arguments: {arguments}")
              if not arguments.get("playlist_id"):
                  logger.error("playlist_id is required for get_tracks action.")
                  return create_error_response("playlist_id is required for get_tracks action.")
              tracks = spotify_client.get_playlist_tracks(arguments.get("playlist_id"))
              return [types.TextContent(
                  type="text",
                  text=json.dumps(tracks, indent=2)
              )]
          case "add_tracks":
              logger.info(f"Adding tracks to playlist with arguments: {arguments}")
              track_ids = arguments.get("track_ids")
              if isinstance(track_ids, str):
                  try:
                      track_ids = json.loads(track_ids)  # Convert JSON string to Python list
                  except json.JSONDecodeError:
                      logger.error("track_ids must be a list or a valid JSON array.")
                      return create_error_response("track_ids must be a list or a valid JSON array.")
  
              spotify_client.add_tracks_to_playlist(
                  playlist_id=arguments.get("playlist_id"),
                  track_ids=track_ids
              )
              return [types.TextContent(
                  type="text",
                  text="Tracks added to playlist."
              )]
          case "remove_tracks":
              logger.info(f"Removing tracks from playlist with arguments: {arguments}")
              track_ids = arguments.get("track_ids")
              if isinstance(track_ids, str):
                  try:
                      track_ids = json.loads(track_ids)  # Convert JSON string to Python list
                  except json.JSONDecodeError:
                      logger.error("track_ids must be a list or a valid JSON array.")
                      return create_error_response("track_ids must be a list or a valid JSON array.")
  
              spotify_client.remove_tracks_from_playlist(
                  playlist_id=arguments.get("playlist_id"),
                  track_ids=track_ids
              )
              return [types.TextContent(
                  type="text",
                  text="Tracks removed from playlist."
              )]
  
          case "change_details":
              logger.info(f"Changing playlist details with arguments: {arguments}")
              if not arguments.get("playlist_id"):
                  logger.error("playlist_id is required for change_details action.")
                  return create_error_response("playlist_id is required for change_details action.")
              if not arguments.get("name") and not arguments.get("description"):
                  logger.error("At least one of name, description or public is required.")
                  return create_error_response(
                      "At least one of name, description, public, or collaborative is required.")
  
              spotify_client.change_playlist_details(
                  playlist_id=arguments.get("playlist_id"),
                  name=arguments.get("name"),
                  description=arguments.get("description")
              )
              return [types.TextContent(
                  type="text",
                  text="Playlist details changed."
              )]
  
          case _:
              return create_error_response(
                  f"Unknown playlist action: {action}. Supported actions are: get, get_tracks, add_tracks, remove_tracks, change_details.")
  case _:

• src/spotify_mcp/server.py:88-102 (schema)

  Pydantic schema defining inputs for the SpotifyPlaylist tool.

  class Playlist(ToolModel):
      """Manage Spotify playlists.
      - get: Get a list of user's playlists.
      - get_tracks: Get tracks in a specific playlist.
      - add_tracks: Add tracks to a specific playlist.
      - remove_tracks: Remove tracks from a specific playlist.
      - change_details: Change details of a specific playlist.
      """
      action: str = Field(
          description="Action to perform: 'get', 'get_tracks', 'add_tracks', 'remove_tracks', 'change_details'.")
      playlist_id: Optional[str] = Field(default=None, description="ID of the playlist to manage.")
      track_ids: Optional[List[str]] = Field(default=None, description="List of track IDs to add/remove.")
      name: Optional[str] = Field(default=None, description="New name for the playlist.")
      description: Optional[str] = Field(default=None, description="New description for the playlist.")

• src/spotify_mcp/server.py:43-50 (registration)

  Base ToolModel class with as_tool method that names the tool 'SpotifyPlaylist' for Playlist class.

  class ToolModel(BaseModel):
      @classmethod
      def as_tool(cls):
          return types.Tool(
              name="Spotify" + cls.__name__,
              description=cls.__doc__,
              inputSchema=cls.model_json_schema()
          )

• src/spotify_mcp/server.py:119-125 (registration)

  Registration of the SpotifyPlaylist tool (Playlist.as_tool()) in the list_tools handler.

  tools = [
      Playback.as_tool(),
      Search.as_tool(),
      Queue.as_tool(),
      GetInfo.as_tool(),
      Playlist.as_tool(),
  ]