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