Plex MCP Server

Instructions

Implementation Reference

• src/plex_mcp/plex_mcp.py:319-344 (handler)

  The main handler function for the 'list_playlists' tool. It fetches all playlists from the Plex server using the singleton PlexClient, formats each using the format_playlist helper, and returns a formatted string response.

  @mcp.tool()
  async def list_playlists() -> str:
      """
      List all playlists in the Plex server.
      
      Returns:
          A formatted string of playlists 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:
          playlists = await asyncio.to_thread(plex.playlists)
          if not playlists:
              return "No playlists found in your Plex server."
          formatted_playlists = []
          for i, playlist in enumerate(playlists, 1):
              formatted_playlists.append(
                  f"Playlist #{i}:\nKey: {playlist.ratingKey}\n{format_playlist(playlist)}"
              )
          return "\n---\n".join(formatted_playlists)
      except Exception as e:
          logger.exception("Failed to fetch playlists")
          return f"ERROR: Failed to fetch playlists. {str(e)}"

• src/plex_mcp/plex_mcp.py:62-82 (helper)

  Supporting utility function used by list_playlists to format individual playlist information including title, item count, total duration, and last updated timestamp.

  def format_playlist(playlist) -> str:
      """
      Format a playlist into a human-readable string.
      
      Parameters:
          playlist: A Plex playlist object.
          
      Returns:
          A formatted string containing playlist details.
      """
      duration_mins = sum(item.duration for item in playlist.items()) // 60000 if playlist.items() else 0
      updated = (
          playlist.updatedAt.strftime('%Y-%m-%d %H:%M:%S')
          if hasattr(playlist, 'updatedAt') else 'Unknown'
      )
      return (
          f"Playlist: {playlist.title}\n"
          f"Items: {len(playlist.items())}\n"
          f"Duration: {duration_mins} minutes\n"
          f"Last Updated: {updated}\n"
      )

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

  Package __init__.py imports and exposes list_playlists from plex_mcp.py, making it available for use as an MCP tool.

  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,
  )

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

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

  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