README.md•5.2 kB
# 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.