search_playlists
Find YouTube playlists by entering a search query, with options to set result limits and output formats for playlist metadata.
Instructions
Search YouTube for playlists matching a query.
Args: query: Search query string (e.g., "python tutorial playlist") max_results: Maximum number of results to return (1-50, default: 10) output_format: Output format - "json" or "markdown" (default: "json")
Returns: Formatted search results with playlist metadata
Example: search_playlists("machine learning course", max_results=5, output_format="json")
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| max_results | No | ||
| output_format | No | json |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- The handler function `search_playlists` which is registered as an MCP tool. It validates the input, calls the search provider, formats the results, and handles exceptions.
@mcp.tool() async def search_playlists( query: str, max_results: int = 10, output_format: str = "json" ) -> str: """ Search YouTube for playlists matching a query. Args: query: Search query string (e.g., "python tutorial playlist") max_results: Maximum number of results to return (1-50, default: 10) output_format: Output format - "json" or "markdown" (default: "json") Returns: Formatted search results with playlist metadata Example: search_playlists("machine learning course", max_results=5, output_format="json") """ try: logger.info(f"Playlist search request: query='{query}', max_results={max_results}") # Validate query validated_query = validate_query(query) # Execute search provider = get_search_provider() playlists = await provider.search_playlists(validated_query, max_results) # Format results formatter = get_formatter(output_format) result = formatter.format_playlists(playlists) logger.info(f"Playlist search completed: found {len(playlists)} playlists") return result except InvalidQueryError as e: logger.warning(f"Invalid query: {e.message}") return json.dumps({"error": "invalid_query", "message": e.message}) except NetworkError as e: logger.error(f"Network error: {e.message}") return json.dumps( { "error": "network_error", "message": "Failed to connect to YouTube. Please try again.", "details": e.message, } ) except SearchProviderError as e: logger.error(f"Search provider error: {e.message}", exc_info=True) return json.dumps( { "error": "search_failed", "message": "Playlist search operation failed. Please try a different query.", "details": e.message, } ) except Exception: logger.exception("Unexpected error in search_playlists") return json.dumps( { "error": "internal_error", "message": "An unexpected error occurred. Please try again later.", } ) - src/youtube_search_mcp/tools/playlist_tools.py:21-27 (registration)The `register_playlist_tools` function that registers the tools to the FastMCP instance.
def register_playlist_tools(mcp: FastMCP) -> None: """ Register all playlist-related tools with the MCP server. Args: mcp: FastMCP server instance """