# 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.

1.  **Install `uv`**:
    If you don't have `uv`, install it using the recommended command from Astral:
    ```sh
    curl -LsSf https://astral.sh/uv/install.sh | sh
    ```

2.  **Create a virtual environment and install dependencies**:
    ```sh
    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:
    ```sh
    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:

```sh
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:

```sh
./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:

```json
{
  "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.