An MCP server that provides tools for YouTube content analysis, including transcript extraction, video search, and channel information retrieval. Integrates with OpenAI agents for AI-powered YouTube content analysis.
YouTube Agent MCP Server exhibits significant definition quality gaps across all three tools. Tool naming is clear (verb-first pattern observed), but descriptions are written in Korean without proper localization strategy, parameter descriptions are minimal or missing, and output schemas are not documented. Error handling returns generic exceptions without recovery guidance. The server exposes API keys via environment variables but the security of this pattern is not auditable from the code. Input schemas are present but lack detailed constraints and type information for complex outputs.
Tool descriptions are exclusively in Korean with no English fallback. Non-Korean-speaking LLMs and users cannot understand when or why to invoke these tools.
Output schemas for all three tools are completely undocumented. search_youtube_videos returns a list of video objects with 8 fields (title, publishedDate, channelName, channelId, thumbnailUrl, viewCount, likeCount, url); get_channel_info returns a dict with nested arrays. LLMs cannot infer or plan downstream operations without seeing these schemas.
Error handling does not guide LLM recovery. search_youtube_videos returns empty list [] on error instead of raising exception, LLM cannot distinguish 'no results' from 'API failure'. get_channel_info raises ValueError with bare messages ('Invalid YouTube URL') offering no hints on valid formats or alternative actions.
search_youtube_videos
Recommendations
Rewrite all tool descriptions in English, following the pattern: '[WHAT] Retrieves [RESOURCE]. [WHEN] Use this when you need [SPECIFIC_USE_CASE] instead of [ALTERNATIVE_TOOL]. [RETURNS] Returns [FIELDS]. [PARAMS] Requires [CONSTRAINTS].' Example: 'Retrieves a YouTube video transcript in Korean or English. Use this to analyze video content; use search_youtube_videos to find videos by keyword. Returns transcript as plain text. Requires valid YouTube URL (youtube.com/watch?v=VIDEO_ID or youtu.be/VIDEO_ID).'
Document output schemas for all three tools. Use JSON Schema format or pseudo-code. Example for search_youtube_videos: '{items: [{title: string, publishedDate: ISO8601, channelName: string, channelId: string, thumbnailUrl: string, viewCount: int, likeCount: int, url: string}], totalResults: int, pageInfo: {resultsPerPage: int, totalResults: int}}'
Add format validation to input parameters. For 'url' params: specify regex pattern '^https?://(www\.)?youtu(be\.com|.be)/' and document valid formats (youtube.com/watch?v=ID, youtu.be/ID). For 'query' param: document length limits (1-100 chars), forbidden characters, and search behavior (partial match vs exact).
Implement proper error handling with recovery guidance. Instead of returning empty list on error, raise an exception with a message like: 'YouTube API search failed: Invalid API key or quota exceeded. Verify YOUTUBE_API_KEY is set and quota is available.' For URL validation, return: 'Invalid YouTube URL. Expected format: youtube.com/watch?v=VIDEO_ID or youtu.be/VIDEO_ID. Got: {user_input}'
Input parameters lack format constraints and validation rules. 'url' parameters accept any string but should specify YouTube URL format (regex, examples, character limits). 'query' parameter for search has no length bounds, forbidden characters, or guidance on partial vs exact match behavior.
Tool naming ambiguity: search_youtube_videos and get_channel_info both return channel-related information. LLMs will struggle to select the correct tool. Descriptions should clearly state when to use each (e.g., 'Use search_youtube_videos to find videos by keyword; use get_channel_info to get full channel stats and recent uploads from a known video').
No parameter descriptions for input fields in some cases. 'url' and 'video_url' parameters lack detail on expected format, validation rules, or examples. This violates the baseline that 100% of A+ tool params have descriptions.
Result limits are hardcoded but not transparent. search_youtube_videos hardcodes max_results=20 and get_channel_info hardcodes recent videos=5. These limits should be user-selectable parameters or clearly documented in tool descriptions to set LLM expectations.
search_youtube_videosget_channel_info
Add max_results and limit parameters to search_youtube_videos and get_channel_info, allowing LLMs to request different result set sizes. Default to 20 and 5 respectively, but allow 1-50 range.
Clarify tool selection by enhancing descriptions with 'INSTEAD OF' hints. search_youtube_videos description: 'Use this to FIND videos by keyword (search). For channel stats and recent uploads from a known video, use get_channel_info instead.'
Add parameter descriptions to all input fields. Example: 'url: YouTube video URL in format youtube.com/watch?v=VIDEO_ID or youtu.be/VIDEO_ID. Used to extract transcript or channel information.'
Return structured responses with explicit field names and types. For get_youtube_transcript, return {transcript: string, language: string, videoId: string} instead of plain string. For search_youtube_videos, return {videos: [...], totalResults: int} instead of raw list.
Add per-field validation in the implementation with clear error messages. If URL regex fails: raise ValueError(f'Invalid YouTube URL format: {url}. Expected youtube.com/watch?v=... or youtu.be/...'). If API key is missing: raise RuntimeError('YOUTUBE_API_KEY environment variable not set. Configure it in .env file.').
Document pagination: 'Returns up to 20 results per call. Call again with a cursor or page parameter to fetch more.' Implement cursor-based or offset-based pagination if the service requires it.