Plex MCP Server

Instructions

Implementation Reference

• src/plex_mcp/plex_mcp.py:288-318 (handler)

  The core handler function for the get_movie_details tool. It connects to the Plex server, searches for the movie by its ratingKey, and returns formatted details using the format_movie helper or appropriate error messages.

  @mcp.tool()
  async def get_movie_details(movie_key: str) -> str:
      """
      Get detailed information about a specific movie.
      
      Parameters:
          movie_key: The key identifying the movie.
          
      Returns:
          A formatted string with movie 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:
          key = int(movie_key)
  
          all_movies = await asyncio.to_thread(lambda: plex.library.search(libtype="movie"))
          movie = next((m for m in all_movies if m.ratingKey == key), None)
  
          if not movie:
              return f"No movie found with key {movie_key}."
          return format_movie(movie)
      except NotFound:
          return f"ERROR: Movie with key {movie_key} not found."
      except Exception as e:
          logger.exception("Failed to fetch movie details for key '%s'", movie_key)
          return f"ERROR: Failed to fetch movie details. {str(e)}"

• src/plex_mcp/plex_mcp.py:33-60 (helper)

  Utility function that formats a Plex movie object into a detailed human-readable string, called by get_movie_details to present the movie information.

  def format_movie(movie) -> str:
      """
      Format a movie object into a human-readable string.
      
      Parameters:
          movie: A Plex movie object.
          
      Returns:
          A formatted string containing movie details.
      """
      title = getattr(movie, 'title', 'Unknown Title')
      year = getattr(movie, 'year', 'Unknown Year')
      summary = getattr(movie, 'summary', 'No summary available')
      duration = getattr(movie, 'duration', 0) // 60000 if hasattr(movie, 'duration') else 0
      rating = getattr(movie, 'rating', 'Unrated')
      studio = getattr(movie, 'studio', 'Unknown Studio')
      directors = [director.tag for director in getattr(movie, 'directors', [])[:3]]
      actors = [role.tag for role in getattr(movie, 'roles', [])[:5]]
      
      return (
          f"Title: {title} ({year})\n"
          f"Rating: {rating}\n"
          f"Duration: {duration} minutes\n"
          f"Studio: {studio}\n"
          f"Directors: {', '.join(directors) if directors else 'Unknown'}\n"
          f"Starring: {', '.join(actors) if actors else 'Unknown'}\n"
          f"Summary: {summary}\n"
      )

• src/plex_mcp/plex_mcp.py:198-215 (helper)

  Helper function to asynchronously obtain a PlexServer instance using a singleton PlexClient, used by get_movie_details for server connection.

  async def get_plex_server() -> PlexServer:
      """
      Asynchronously get a PlexServer instance via the singleton PlexClient.
      
      Returns:
          A PlexServer instance.
          
      Raises:
          Exception: When the Plex server connection fails.
      """
      try:
          plex_client = get_plex_client()  # Singleton accessor
          plex = await asyncio.to_thread(plex_client.get_server)
          return plex
      except Exception as e:
          logger.exception("Failed to get Plex server instance")
          raise e

• src/plex_mcp/plex_mcp.py:288-289 (registration)

  The @mcp.tool() decorator registers the get_movie_details function as an MCP tool, with input schema inferred from type hints (movie_key: str) and output str.

  @mcp.tool()
  async def get_movie_details(movie_key: str) -> str: