Plex MCP Server

Instructions

Implementation Reference

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

  The core handler function for the 'create_playlist' tool. It is decorated with @mcp.tool() which registers it with FastMCP. The function fetches movies by keys, validates them, and creates a new playlist using the Plex API.
  @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)}"