YouTube Insights MCP Server

Instructions

Implementation Reference

• src/youtubeinsights_mcp_server/server.py:37-89 (handler)

  The complete handler function for search_youtube_videos, registered with @mcp.tool() decorator. It searches YouTube videos using the YouTube Data API, fetching search results and detailed video information (snippet, statistics) including title, published date, channel info, thumbnails, view count, like count, and video URL.

  @mcp.tool()
  def search_youtube_videos(query: str):
      """Search YouTube videos by keyword and retrieve detailed information"""
      try:
          max_results: int = 20
          search_url = (f"{YOUTUBE_API_URL}/search?part=snippet&q={quote(query)}"
                        f"&type=video&maxResults={max_results}&key={YOUTUBE_API_KEY}")
  
          search_response = httpx.get(search_url)
          search_response.raise_for_status()
          search_data = search_response.json()
          video_ids = [item['id']['videoId'] for item in search_data.get('items', [])]
  
          if not video_ids:
              print("No videos found for the query.")
              return []
  
          video_details_url = (f"{YOUTUBE_API_URL}/videos?part=snippet,statistics&id={','.join(video_ids)}"
                               f"&key={YOUTUBE_API_KEY}")
          details_response = httpx.get(video_details_url)
          details_response.raise_for_status()
          details_data = details_response.json()
  
          videos = []
          for item in details_data.get('items', []):
              snippet = item.get('snippet', {})
              statistics = item.get('statistics', {})
              thumbnails = snippet.get('thumbnails', {})
              high_thumbnail = thumbnails.get('high', {}) 
              view_count = statistics.get('viewCount')
              like_count = statistics.get('likeCount')
  
              video_card = {
                  "title": snippet.get('title', 'N/A'),
                  "publishedDate": snippet.get('publishedAt', ''),
                  "channelName": snippet.get('channelTitle', 'N/A'),
                  "channelId": snippet.get('channelId', ''),
                  "thumbnailUrl": high_thumbnail.get('url', ''),
                  "viewCount": int(view_count) if view_count is not None else None,
                  "likeCount": int(like_count) if like_count is not None else None,
                  "url": f"https://www.youtube.com/watch?v={item.get('id', '')}",
              }
              videos.append(video_card)
  
          if not videos:
              print("No video details could be fetched.")
              return []
  
          return videos
  
      except Exception as e:
          print(f"Error: {e}")
          return []

• src/youtubeinsights_mcp_server/server.py:37-39 (schema)

  The input schema for search_youtube_videos is implicitly defined by the function signature (query: str) and docstring. FastMCP automatically generates the JSON schema from Python type hints and docstrings. The function accepts a single 'query' string parameter representing the search keyword.

  @mcp.tool()
  def search_youtube_videos(query: str):
      """Search YouTube videos by keyword and retrieve detailed information"""

• src/youtubeinsights_mcp_server/server.py:37-37 (registration)

  The tool registration using FastMCP's @mcp.tool() decorator. This registers search_youtube_videos as an MCP tool, making it available to the MCP server for client invocation.

  @mcp.tool()