Plex MCP Server

Instructions

Implementation Reference

• src/plex_mcp/plex_mcp.py:478-520 (handler)

  The core implementation of the 'add_to_playlist' tool. This async function, decorated with @mcp.tool(), handles adding a movie to a playlist using the Plex API. It includes input validation, playlist and movie lookup, and error handling.

  @mcp.tool()
  async def add_to_playlist(playlist_key: str, movie_key: str) -> str:
      """
      Add a movie to an existing playlist.
      
      Parameters:
          playlist_key: The key of the playlist.
          movie_key: The key of the movie to add.
          
      Returns:
          A success message if the movie is added, 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:
          p_key = int(playlist_key)
          m_key = int(movie_key)
  
          # Find the playlist
          all_playlists = await asyncio.to_thread(plex.playlists)
          playlist = next((p for p in all_playlists if p.ratingKey == p_key), None)
          if not playlist:
              return f"No playlist found with key {playlist_key}."
  
          # Perform a global search for the movie
          movies = await asyncio.to_thread(lambda: plex.library.search(libtype="movie", ratingKey=m_key))
          if not movies:
              return f"No movie found with key {movie_key}."
  
          movie = movies[0]  # Since the search is scoped to the ratingKey, there should be at most one result
  
          # Add the movie to the playlist
          await asyncio.to_thread(lambda p=playlist, m=movie: p.addItems([m]))
          logger.info("Added movie '%s' to playlist '%s'", movie.title, playlist.title)
          return f"Successfully added '{movie.title}' to playlist '{playlist.title}'."
      except ValueError:
          return "ERROR: Invalid playlist or movie key. Please provide valid numbers."
      except Exception as e:
          logger.exception("Failed to add movie to playlist")
          return f"ERROR: Failed to add movie to playlist. {str(e)}"

• src/plex_mcp/__init__.py:1-27 (registration)

  Package __init__.py re-exports the add_to_playlist function, making it available when importing from the plex_mcp package.

  from .plex_mcp import (
      search_movies,
      get_movie_details,
      list_playlists,
      get_playlist_items,
      create_playlist,
      delete_playlist,
      add_to_playlist,
      recent_movies,
      get_movie_genres,
      get_plex_server,
      MovieSearchParams,
  )
  
  __all__ = [
      "search_movies",
      "get_movie_details",
      "list_playlists",
      "get_playlist_items",
      "create_playlist",
      "delete_playlist",
      "add_to_playlist",
      "recent_movies",
      "get_movie_genres",
      "get_plex_server",
      "MovieSearchParams",
  ]