Plex MCP Server

Instructions

Implementation Reference

• src/plex_mcp/plex_mcp.py:386-446 (handler)

  The handler function implementing the 'create_playlist' MCP tool. It parses comma-separated movie keys, retrieves movies from the Plex library, creates a playlist using plex.createPlaylist, handles timeouts and errors, and returns a formatted success or error message.
  @mcp.tool() async def create_playlist(name: str, movie_keys: str) -> str: """ Create a new playlist with specified movies. Parameters: name: The desired name for the new playlist. movie_keys: A comma-separated string of movie keys to include. Returns: A success message with playlist 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: movie_key_list = [int(key.strip()) for key in movie_keys.split(",") if key.strip()] if not movie_key_list: return "ERROR: No valid movie keys provided." logger.info("Creating playlist '%s' with movie keys: %s", name, movie_keys) all_movies = await asyncio.to_thread(lambda: plex.library.search(libtype="movie")) logger.info("Found %d total movies in library", len(all_movies)) movie_map = {movie.ratingKey: movie for movie in all_movies} movies = [] not_found_keys = [] for key in movie_key_list: if key in movie_map: movies.append(movie_map[key]) logger.info("Found movie: %s (Key: %d)", movie_map[key].title, key) else: not_found_keys.append(key) logger.warning("Could not find movie with key: %d", key) if not_found_keys: return f"ERROR: Some movie keys were not found: {', '.join(str(k) for k in not_found_keys)}" if not movies: return "ERROR: No valid movies found with the provided keys." try: playlist_future = asyncio.create_task( asyncio.to_thread(lambda: plex.createPlaylist(name, items=movies)) ) playlist = await asyncio.wait_for(playlist_future, timeout=15.0) logger.info("Playlist created successfully: %s", playlist.title) return f"Successfully created playlist '{name}' with {len(movies)} movie(s).\nPlaylist Key: {playlist.ratingKey}" except asyncio.TimeoutError: logger.warning("Playlist creation is taking longer than expected for '%s'", name) return ("PENDING: Playlist creation is taking longer than expected. " "The operation might still complete in the background. " "Please check your Plex server to confirm.") except ValueError as e: logger.error("Invalid input format for movie keys: %s", e) return f"ERROR: Invalid input format. Please check movie keys are valid numbers. {str(e)}" except Exception as e: logger.exception("Error creating playlist") return f"ERROR: Failed to create playlist. {str(e)}"
• src/plex_mcp/__init__.py:1-13 (registration)

  Package __init__.py imports and exposes the create_playlist tool function from plex_mcp.py, making it available for use 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, )
• src/plex_mcp/plex_mcp.py:198-215 (helper)

  Helper function used by create_playlist to asynchronously obtain and return the PlexServer instance.
  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:387-397 (schema)

  Input schema defined by function parameters (name: str, movie_keys: str) and output (str), with descriptive docstring for MCP tool schema.
  async def create_playlist(name: str, movie_keys: str) -> str: """ Create a new playlist with specified movies. Parameters: name: The desired name for the new playlist. movie_keys: A comma-separated string of movie keys to include. Returns: A success message with playlist details or an error message. """