Plex MCP Server

Instructions

Implementation Reference

• src/plex_mcp/plex_mcp.py:559-593 (handler)

  The core handler function for the 'get_movie_genres' tool, decorated with @mcp.tool(). It connects to Plex, searches for the movie by key, extracts its genres, and returns a formatted string or error message.

  @mcp.tool()
  async def get_movie_genres(movie_key: str) -> str:
      """
      Get genres for a specific movie.
      
      Parameters:
          movie_key: The key of the movie.
          
      Returns:
          A formatted string of movie genres 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)
  
          # Perform a global search for the movie
          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}."
  
          # Extract genres
          genres = [genre.tag for genre in movie.genres] if hasattr(movie, 'genres') else []
          if not genres:
              return f"No genres found for movie '{movie.title}'."
          return f"Genres for '{movie.title}':\n{', '.join(genres)}"
      except ValueError:
          return f"ERROR: Invalid movie key '{movie_key}'. Please provide a valid number."
      except Exception as e:
          logger.exception("Failed to fetch genres for movie with key '%s'", movie_key)
          return f"ERROR: Failed to fetch movie genres. {str(e)}"

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

  The __init__.py file re-exports the get_movie_genres tool (along with others) via import and __all__, 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",
  ]

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

  Helper function used by get_movie_genres to asynchronously obtain the PlexServer instance via a singleton PlexClient.

  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