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: