yt-fetch MCP Server

yt-fetch is a Model-Context-Protocol (MCP) server designed to provide tools and resources for interacting with the YouTube metadata and transcripts. It allows a client (like Claude 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.

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.

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
```
Create a virtual environment and install dependencies:
```
uv venv
uv pip install -e .
```
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:

Verify that your YOUTUBE_API_KEY is set.
Determine the correct path for your Claude Desktop configuration.
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.