# YouTube MCP Server

A production-quality Model Context Protocol (MCP) server that empowers LLMs to seamlessly interact with YouTube videos. This server exposes tools to fetch video transcripts, actively summarize videos, and accurately answer questions based on the video context.

## 🌟 Features
- **Fetch Transcripts**: Extracts subtitles intelligently, translating generated transcripts to English if necessary.
- **Smart Summarization**: Chunks large videos into smaller segments to bypass LLM context limit bottlenecks automatically.
- **Q&A System**: Query specific details from massive YouTube videos directly.
- **Fast Performance**: Transcripts are temporarily cached in memory. Async architecture scaling cleanly.
- **Resilience**: Integrated exponential backoff and retry mechanism for LLM API calls using `tenacity`.

## 📁 Project Structure

```text
youtube_mcp_server/
├── server.py        # Initializes MCP server and exposes tool endpoints
├── tools.py         # The core logic mapping transcript APIs to caching and chunking
├── utils.py         # URL extraction, text cleaning, and chunking utility functions
├── llm.py           # The LLM engine wrapper managing API requests and retries
├── requirements.txt # Project pip dependencies
└── README.md        # Documentation
```

## 🚀 Installation

1. Clone or navigate to this folder.
2. It's recommended to create a Python virtual environment:
   ```bash
   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```
3. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```

## 🔑 Configuration

You must set up your OpenAI API key for `summarize_video` and `ask_video` to function.

```bash
export OPENAI_API_KEY="your-api-key-here"
# Optional: Set a specific model (defaults to gpt-4o-mini)
export LLM_MODEL="gpt-4o"
```

## 🎮 How to Run

Because this is an MCP server, it is meant to communicate via standard input/output (stdio) with an MCP Client (such as Claude Desktop, Cursor, or an intelligent agent).

You can run it manually to see it start to listen on stdio:
```bash
python server.py
```

### 🤝 Connecting from an MCP Client (Example: Claude Desktop)

To use this server inside Claude Desktop, add it to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "youtube_server": {
      "command": "/path/to/your/venv/bin/python",
      "args": ["/path/to/youtube_mcp_server/server.py"],
      "env": {
        "OPENAI_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

## 📋 Example Tool Usage (Client Perspective)

Once connected, your LLM context will see three available tools:

**1. `get_transcript(video_url="https://youtube.com/watch?v=XXXX")`**
- *LLM use case:* "Retrieve the script for this video so I can parse a recipe."

**2. `summarize_video(video_url="https://youtu.be/XXXX")`**
- *LLM use case:* "Can you give me a summary of Marques Brownlee's latest review?"

**3. `ask_video(video_url="https://youtube.com/watch?v=XXXX", question="What was the score they mentioned?")`**
- *LLM use case:* "From the meeting recording link, what were the Q3 metrics discussed?"

### Example Tool Responses

**Summarize Video Response**:
> "The video discusses the release of the new MacBook Pro M4. Key points include:
> 1. Performance upgrades with the M4 chip over the previous generation.
> 2. The introduction of the new Nano-texture display.
> 3. Improvements in battery life averaging 20 hours. 
> The presenter concludes that it is a solid upgrade for M1 users, but M3 users can hold off."

**Ask Video Response**:
> "Based on the video transcript, the presenter stated that the starting price for the base model is $1,599."

## 🛠 Troubleshooting

- **No module named 'mcp'**: Make sure you have installed the requirements `pip install -r requirements.txt`.
- **Transcripts Disabled**: Some creators disable transcripts on their YouTube videos. The server elegantly catches this and returns a clear text Error instead of crashing the server.
- **LLM Fails to Output (API Key missing)**: If `OPENAI_API_KEY` is not provided in the environment variables where the MCP server is initialized, the server's summarise and QA tool executions will yield an error message indicating the problem.