YouTube Toolbox

Instructions

Implementation Reference

• server.py:1053-1131 (handler)

  Primary MCP tool handler for get_video_comments. Processes parameters, calls YouTubeService.get_video_comments, formats top-level comments and optional replies into structured JSON response with pagination info.

  @mcp.tool(
      name="get_video_comments",
      description="Get comments for a YouTube video",
  )
  async def get_video_comments(
      video_id: str, 
      max_results: Optional[int] = 20, 
      order: Optional[str] = "relevance", 
      include_replies: bool = False,
      page_token: Optional[str] = None
  ) -> Dict[str, Any]:
      """
      Get comments for a YouTube video
      
      Args:
          video_id (str): YouTube video ID
          max_results (int): Maximum number of comments to return (default: 20)
          order (str): Order by 'relevance' (default) or 'time'
          include_replies (bool): Whether to include replies to comments
          page_token (str, optional): Token for paginated results
      
      Returns:
          Dict[str, Any]: Comments data
      """
      try:
          options = {
              'order': order,
              'includeReplies': include_replies,
          }
          
          if page_token:
              options['pageToken'] = page_token
              
          comments_data = youtube_service.get_video_comments(video_id, max_results, **options)
          
          # Format the response
          formatted_comments = []
          for item in comments_data.get('items', []):
              comment = item.get('snippet', {}).get('topLevelComment', {}).get('snippet', {})
              
              formatted_comment = {
                  'id': item.get('id'),
                  'text': comment.get('textDisplay'),
                  'author': comment.get('authorDisplayName'),
                  'authorProfileImageUrl': comment.get('authorProfileImageUrl'),
                  'likeCount': comment.get('likeCount'),
                  'publishedAt': comment.get('publishedAt'),
                  'updatedAt': comment.get('updatedAt'),
                  'replyCount': item.get('snippet', {}).get('totalReplyCount', 0)
              }
              
              # Include replies if requested and available
              if include_replies and 'replies' in item:
                  reply_comments = []
                  for reply in item.get('replies', {}).get('comments', []):
                      reply_snippet = reply.get('snippet', {})
                      reply_comments.append({
                          'id': reply.get('id'),
                          'text': reply_snippet.get('textDisplay'),
                          'author': reply_snippet.get('authorDisplayName'),
                          'authorProfileImageUrl': reply_snippet.get('authorProfileImageUrl'),
                          'likeCount': reply_snippet.get('likeCount'),
                          'publishedAt': reply_snippet.get('publishedAt'),
                          'updatedAt': reply_snippet.get('updatedAt')
                      })
                  
                  formatted_comment['replies'] = reply_comments
                  
              formatted_comments.append(formatted_comment)
              
          return {
              'comments': formatted_comments,
              'nextPageToken': comments_data.get('nextPageToken'),
              'totalResults': comments_data.get('pageInfo', {}).get('totalResults', 0)
          }
      except Exception as e:
          logger.exception(f"Error in get_video_comments: {e}")
          return {'error': str(e)}

• server.py:284-311 (helper)

  Core helper method in YouTubeService class that constructs and executes the YouTube Data API v3 commentThreads.list request, handling URL parsing, parameters like order/pageToken/includeReplies, and error handling.

  def get_video_comments(self, video_id: str, max_results: int = 20, **options) -> Dict[str, Any]:
      """
      Get comments for a specific YouTube video
      """
      video_id = self.parse_url(video_id)
      
      try:
          params = {
              'part': 'snippet',
              'videoId': video_id,
              'maxResults': max_results
          }
          
          if 'order' in options:
              params['order'] = options['order']
              
          if 'pageToken' in options:
              params['pageToken'] = options['pageToken']
              
          if options.get('includeReplies'):
              params['part'] = 'snippet,replies'
              
          response = self.youtube.commentThreads().list(**params).execute()
          return response
      except HttpError as e:
          logger.error(f"Error getting comments: {e}")
          raise e

• server.py:1053-1056 (registration)

  MCP tool registration decorator specifying the tool name and description.

  @mcp.tool(
      name="get_video_comments",
      description="Get comments for a YouTube video",
  )

• server.py:1057-1063 (schema)

  Input schema inferred from function parameters: video_id (required str), max_results (opt int=20), order (opt str="relevance"), include_replies (opt bool=False), page_token (opt str). Output: Dict with comments list, nextPageToken, totalResults.

  async def get_video_comments(
      video_id: str, 
      max_results: Optional[int] = 20, 
      order: Optional[str] = "relevance", 
      include_replies: bool = False,
      page_token: Optional[str] = None
  ) -> Dict[str, Any]: