Plex MCP Server

Instructions

Implementation Reference

• src/plex_mcp/plex_mcp.py:346-384 (handler)

  The main handler function for the 'get_playlist_items' tool. It is decorated with @mcp.tool(), takes a playlist_key parameter, connects to the Plex server, fetches the playlist, retrieves its items, and formats them into a numbered list with title, year, and type. Handles errors like not found or connection issues.

  @mcp.tool()
  async def get_playlist_items(playlist_key: str) -> str:
      """
      Get the items in a specific playlist.
      
      Parameters:
          playlist_key: The key of the playlist to retrieve items from.
          
      Returns:
          A formatted string of playlist items 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(playlist_key)
          all_playlists = await asyncio.to_thread(plex.playlists)
          playlist = next((p for p in all_playlists if p.ratingKey == key), None)
          if not playlist:
              return f"No playlist found with key {playlist_key}."
  
          items = playlist.items()
          if not items:
              return "No items found in this playlist."
  
          formatted_items = []
          for i, item in enumerate(items, 1):
              title = item.title
              year = getattr(item, 'year', '')
              type_str = item.type.capitalize()
              formatted_items.append(f"{i}. {title} ({year}) - {type_str}")
          return "\n".join(formatted_items)
      except NotFound:
          return f"ERROR: Playlist with key {playlist_key} not found."
      except Exception as e:
          logger.exception("Failed to fetch items for playlist key '%s'", playlist_key)
          return f"ERROR: Failed to fetch playlist items. {str(e)}"

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

  The __init__.py file re-exports the get_playlist_items function (and others) making it available for import, which is part of the tool registration in the package structure.

  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 get_plex_server used by get_playlist_items to obtain the PlexServer instance asynchronously.

  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