yt-fetch MCP Server

yt-fetch is a Model-Context-Protocol (MCP) server designed to provide tools and resources for interacting with the YouTube Data API v3. It allows a client (like Claude for Desktop) to search for videos, retrieve video and channel details, analyze trends, and fetch video transcripts.

Features

• Search Videos: Comprehensive search with filters for date, duration, order, and more.
• Video & Channel Details: Fetch detailed metadata for specific videos and channels.
• Transcript Analysis: Extract and analyze video transcripts.
• Trending Videos: Get insights into trending videos by region and category.
• Custom Filtering: Apply advanced filters on video lists based on views, duration, and keywords.
• Rich Logging: Formatted and colorful logging for better readability.

Tools

The server exposes the following tools:

Tool Name	Description
search_videos	Search YouTube for videos with various filters and sorting options.
get_video_details	Get detailed information about a specific YouTube video.
get_channel_info	Get information about a YouTube channel.
filter_videos	Apply custom filters to a list of videos.
get_transcripts	Extract transcripts from selected videos for detailed analysis.
trending_analysis	Get and analyze trending videos in specific categories.

Resources

The server provides the following resources:

URI	Description
youtube://search/{query}	Cached search results for YouTube videos with metadata.
youtube://video/{video_id}/metadata	Full metadata for a specific YouTube video including stats and details.
youtube://channel/{channel_id}	Channel information including stats, description, and recent videos.

Setup and Installation

This project uses uv for dependency management.

1. Install uv: If you don't have uv, install it using the recommended command from Astral:

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

2. Create a virtual environment and install dependencies:

   uv venv
   uv pip install -e .
   

3. Set up your YouTube API Key: You need a YouTube Data API v3 key. Once you have it, set it as an environment variable:

   export YOUTUBE_API_KEY="your-youtube-api-key-here"
   

   For persistent storage, you can add this to your shell's configuration file (e.g., .zshrc, .bashrc).

Running the Server

You can run the server directly from your terminal:

uv run yt-fetch

The server will start and listen for requests over stdio.

Automated Claude Desktop Configuration

For a seamless setup with Claude Desktop, you can use the included setup_mcp.sh script. This script will automatically detect your operating system, find your Claude Desktop configuration directory, and create the necessary claude_desktop_config.json file for you.

Before running the script, make sure you have set the YOUTUBE_API_KEY environment variable.

To run the script, execute the following command from the root of the project:

./setup_mcp.sh

The script will:

1. Verify that your YOUTUBE_API_KEY is set.
2. Determine the correct path for your Claude Desktop configuration.
3. Generate the claude_desktop_config.json with the correct project path and your API key.

After running the script, simply restart Claude Desktop, and the yt-fetch server will be available.

Claude Desktop Configuration

To use this server with an MCP client like Claude Desktop, you need to configure it in your claude_desktop_config.json. This file tells the client how to start and communicate with the server.

Here is an example configuration. Place this in your Claude Desktop configuration file:

{
  "mcpServers": {
    "yt-fetch": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/path/to/your/yt-fetch", // <-- IMPORTANT: Change this to the absolute path of the project
        "yt-fetch"
      ],
      "env": {
        "YOUTUBE_API_KEY": "your-youtube-api-key-here" // <-- IMPORTANT: Replace with your actual key
      }
    }
  }
}

Key points for the configuration:

• "yt-fetch": This is the name you'll use to refer to the server in your client.
• command: The executable to run. We use uv.
• args: The arguments to pass to the command.
  • --project: Make sure to provide the absolute path to the root of this yt-fetch repository.
  • yt-fetch: This is the script name defined in pyproject.toml.
• env: Environment variables to set for the server process. You must provide your YOUTUBE_API_KEY here.