Plex MCP Server

Instructions

Implementation Reference

• src/plex_mcp/plex_mcp.py:386-446 (handler)

  The core handler function for the 'create_playlist' tool. It is decorated with @mcp.tool() which registers it with FastMCP. The function fetches movies by keys, validates them, and creates a new playlist using the Plex API.

  @mcp.tool()
  async def create_playlist(name: str, movie_keys: str) -> str:
      """
      Create a new playlist with specified movies.
      
      Parameters:
          name: The desired name for the new playlist.
          movie_keys: A comma-separated string of movie keys to include.
          
      Returns:
          A success message with playlist details or an error message.
      """
      try:
          plex = await get_plex_server()
      except Exception as e:
          return f"ERROR: Could not connect to Plex server. {str(e)}"
  
      try:
          movie_key_list = [int(key.strip()) for key in movie_keys.split(",") if key.strip()]
          if not movie_key_list:
              return "ERROR: No valid movie keys provided."
  
          logger.info("Creating playlist '%s' with movie keys: %s", name, movie_keys)
          all_movies = await asyncio.to_thread(lambda: plex.library.search(libtype="movie"))
          logger.info("Found %d total movies in library", len(all_movies))
          movie_map = {movie.ratingKey: movie for movie in all_movies}
          movies = []
          not_found_keys = []
  
          for key in movie_key_list:
              if key in movie_map:
                  movies.append(movie_map[key])
                  logger.info("Found movie: %s (Key: %d)", movie_map[key].title, key)
              else:
                  not_found_keys.append(key)
                  logger.warning("Could not find movie with key: %d", key)
  
          if not_found_keys:
              return f"ERROR: Some movie keys were not found: {', '.join(str(k) for k in not_found_keys)}"
          if not movies:
              return "ERROR: No valid movies found with the provided keys."
  
          try:
              playlist_future = asyncio.create_task(
                  asyncio.to_thread(lambda: plex.createPlaylist(name, items=movies))
              )
              playlist = await asyncio.wait_for(playlist_future, timeout=15.0)
              logger.info("Playlist created successfully: %s", playlist.title)
              return f"Successfully created playlist '{name}' with {len(movies)} movie(s).\nPlaylist Key: {playlist.ratingKey}"
          except asyncio.TimeoutError:
              logger.warning("Playlist creation is taking longer than expected for '%s'", name)
              return ("PENDING: Playlist creation is taking longer than expected. "
                      "The operation might still complete in the background. "
                      "Please check your Plex server to confirm.")
      except ValueError as e:
          logger.error("Invalid input format for movie keys: %s", e)
          return f"ERROR: Invalid input format. Please check movie keys are valid numbers. {str(e)}"
      except Exception as e:
          logger.exception("Error creating playlist")
          return f"ERROR: Failed to create playlist. {str(e)}"