# YouTube MCP Server
Model Contex Protocol (MCP) server that enables AI models to interact with YouTube content through a standardized interface. This server provides a set of tools for video search, content analysis, comment processing, and more.
## š Features
- š **Video Search & Discovery**
- Search YouTube videos
- Get trending videos
- Find related content
- Channel information
- š **Content Analysis**
- Detailed video information
- Channel statistics
- Video transcripts
- Comprehensive summaries
- š¬ **Social Features**
- Comment retrieval
- Comment analysis
- User interaction data
## š Quick Start
### Prerequisites
#### 1. Installing Python
**macOS:**
```bash
# Using Homebrew (recommended)
brew install python@3.11
# Verify installation
python3 --version # Should show Python 3.11.x
```
**Linux (Ubuntu/Debian):**
```bash
# Update package list
sudo apt update
# Install Python
sudo apt install python3.11 python3.11-venv
# Verify installation
python3 --version # Should show Python 3.11.x
```
**Windows:**
1. Download Python installer from [python.org](https://www.python.org/downloads/)
2. Run the installer
3. Check "Add Python to PATH" during installation
4. Open Command Prompt and verify:
```cmd
python --version # Should show Python 3.11.x
```
#### 2. Installing uv
**macOS/Linux:**
```bash
# Install uv using the official installer
curl -LsSf https://astral.sh/uv/install.sh | sh
# Verify installation
uv --version
```
**Windows (PowerShell):**
```powershell
# Install uv using the official installer
(Invoke-WebRequest -Uri "https://astral.sh/uv/install.ps1" -UseBasicParsing).Content | pwsh -Command -
# Verify installation
uv --version
```
**Alternative Installation Methods:**
Using pip (if you prefer):
```bash
# Install uv using pip
pip install uv
# Verify installation
uv --version
```
#### 3. Setting Up Google Cloud Credentials
1. **Create a Google Cloud Project:**
```bash
# Go to Google Cloud Console
https://console.cloud.google.com
# Click on "Select a Project" at the top
# Click "New Project"
# Name it (e.g., "youtube-mcp-server")
# Click "Create"
```
2. **Enable YouTube Data API:**
```bash
# In the Google Cloud Console:
# 1. Go to "APIs & Services" > "Library"
# 2. Search for "YouTube Data API v3"
# 3. Click "Enable"
```
3. **Create OAuth 2.0 Credentials:**
```bash
# In the Google Cloud Console:
# 1. Go to "APIs & Services" > "Credentials"
# 2. Click "Create Credentials" > "OAuth client ID"
# 3. Select "Desktop app" as application type
# 4. Name it (e.g., "YouTube MCP Client")
# 5. Click "Create"
```
4. **Download and Store Credentials:**
```bash
# 1. After creating credentials, click "Download JSON"
# 2. Rename the downloaded file to 'credentials.json'
# 3. Move it to your project root:
mv ~/Downloads/client_secret_*.json ./credentials.json
# Verify the file exists and has correct permissions
ls -l credentials.json # Should show -rw------- (readable only by you)
```
5. **First-time Authentication:**
```bash
# Run the server once to authenticate
python mcp_videos.py
# This will:
# 1. Open your browser
# 2. Ask you to sign in to Google
# 3. Grant permissions to the application
# 4. Create a token.pickle file (automatically ignored by git)
```
ā ļø **Important Security Notes:**
- Never commit `credentials.json` or `token.pickle` to git
- Keep your credentials secure and don't share them
- If credentials are compromised:
1. Go to Google Cloud Console
2. Delete the compromised credentials
3. Create new credentials
4. Update your local `credentials.json`
### Installation
1. Clone the repository:
```bash
git clone https://github.com/yourusername/youtube-mcp-server.git
cd youtube-mcp-server
```
2. Create and activate a virtual environment:
```bash
# Create virtual environment
python -m venv .venv
# Activate virtual environment
# On macOS/Linux:
source .venv/bin/activate
# On Windows (Command Prompt):
.venv\Scripts\activate
# On Windows (PowerShell):
.venv\Scripts\Activate.ps1
```
3. Install dependencies using uv:
```bash
# Install project in editable mode
uv pip install -e .
# If you encounter any SSL errors on macOS, you might need to:
export SSL_CERT_FILE=/etc/ssl/cert.pem
```
4. Set up YouTube API credentials:
- Go to [Google Cloud Console](https://console.cloud.google.com)
- Create a new project
- Enable YouTube Data API v3
- Create credentials (OAuth 2.0 Client ID)
- Download the credentials and save as `client_secrets.json`
### Development Setup
For development, you might want to install additional tools:
```bash
# Install development dependencies
uv pip install -e ".[dev]"
# Install pre-commit hooks
pre-commit install
```
### Configuration
1. Create a `.env` file in the project root:
```env
# Required environment variables
YOUTUBE_API_KEY=your_api_key_here
# Optional configuration
YOUTUBE_API_QUOTA_LIMIT=10000 # Daily quota limit
YOUTUBE_API_REGION=US # Default region
```
2. Verify your setup:
```bash
# Check if credentials are properly set up
ls -l credentials.json # Should exist and be readable
ls -l .env # Should exist and be readable
ls -l token.pickle # Should exist after first authentication
# Test the server
python mcp_videos.py
```
## š ļø Usage
### Starting the Server
```bash
python mcp_videos.py
```
### Available Tools
1. **Search Videos**
```python
@mcp.tool()
async def get_videos(search: str, max_results: int)
```
2. **Get Video Info**
```python
@mcp.tool()
async def get_video_info(video_id: str)
```
3. **Get Channel Details**
```python
@mcp.tool()
async def get_channel_details(channel_id: str)
```
4. **Get Video Comments**
```python
@mcp.tool()
async def get_video_comments_tool(video_id: str, max_results: int = 100)
```
5. **Get Trending Videos**
```python
@mcp.tool()
async def get_trending_videos_tool(region_code: str = "US", max_results: int = 50)
```
6. **Get Related Videos**
```python
@mcp.tool()
async def get_related_videos_tool(video_id: str, max_results: int = 25)
```
7. **Summarize Video**
```python
@mcp.tool()
async def summarize_video(video_id: str, include_comments: bool = True)
```
8. **Generate Video Flash Cards**
```python
@mcp.tool()
async def generate_video_flashcards(
video_id: str,
max_cards: int = 10,
categories: Optional[List[str]] = None,
difficulty: Optional[str] = None
)
```
This tool generates educational flash cards from video content:
- Creates different types of cards (Fill in the blank, Q&A, Definition)
- Includes timestamps for video reference
- Categorizes cards by type and difficulty
- Provides card statistics
Example usage:
```python
# Generate 15 flash cards from a video
cards = generate_video_flashcards(
video_id="dQw4w9WgXcQ",
max_cards=15,
categories=["Q&A", "Definition"],
difficulty="Medium"
)
# Generate all types of cards
cards = generate_video_flashcards(
video_id="dQw4w9WgXcQ",
max_cards=20
)
```
Card Types:
- **Fill in the blank**: Tests recall of specific terms or concepts
- **Q&A**: Questions about key points in the video
- **Definition**: Explains important concepts
Difficulty Levels:
- **Easy**: Basic recall and understanding
- **Medium**: Application of concepts
- **Hard**: Complex concepts and relationships
9. **Generate Video Quiz**
```python
@mcp.tool()
async def generate_video_quiz(video_id: str) -> str
```
This tool generates a comprehensive quiz from video content:
- Creates multiple choice questions
- Generates true/false statements
- Includes fill-in-the-blank questions
- Uses video metadata, transcript, and description
- Provides answers and explanations
Example usage:
```python
# Generate a quiz from a video
quiz = generate_video_quiz("dQw4w9WgXcQ")
```
Quiz Features:
- **Multiple Choice Questions**
- Based on video content
- Includes video metadata
- Tests understanding of key concepts
- **True/False Questions**
- Tests factual knowledge
- Based on video statistics
- Verifies understanding of claims
- **Fill in the Blank**
- Tests recall of specific terms
- Uses transcript content
- Focuses on key concepts
Quiz Format:
```python
=== Video Quiz ===
Title: [Video Title]
Channel: [Channel Name]
URL: [Video URL]
Question 1 (Multiple Choice):
[Question text]
1. [Option 1]
2. [Option 2]
3. [Option 3]
4. [Option 4]
Answer: [Correct answer]
------------------
Question 2 (True/False):
[Statement]
Answer: True/False
------------------
Question 3 (Fill in the blank):
[Question with blank]
Answer: [Correct answer]
------------------
```
The quiz tool:
- Generates exactly 10 questions
- Mixes different question types
- Includes video context
- Provides immediate feedback
- Uses video metadata for questions
- Incorporates transcript content
- Tests different levels of understanding
## š Architecture
The project follows a modular architecture:
```mermaid
graph TD
A[LLM Client] --> B[MCP Client]
B --> C[MCP Server]
C --> D[YouTube API]
C --> E[Tool Registry]
C --> F[Data Formatter]
subgraph "Tools"
E --> E1[Video Tools]
E --> E2[Channel Tools]
E --> E3[Comment Tools]
E --> E4[Analysis Tools]
end
```
## š§ Development
### Project Structure
```
youtube-mcp-server/
āāā mcp_videos.py # Main server implementation
āāā youtube_api.py # YouTube API client
āāā yt_helper.py # Helper functions
āāā requirements.txt # Project dependencies
āāā .env # Environment variables
āāā .gitignore # Git ignore rules
āāā README.md # This file
```
### Adding New Tools
1. Create a new async function in `mcp_videos.py`
2. Decorate it with `@mcp.tool()`
3. Implement the tool logic
4. Add appropriate error handling
5. Update documentation
## š API Documentation
### Response Formats
1. **Video Format**
```python
{
"title": str,
"channel_title": str,
"duration": str,
"description": str,
"view_count": int,
"like_count": int,
"comment_count": int,
"url": str,
"published_at": str
}
```
2. **Channel Format**
```python
{
"title": str,
"subscriber_count": int,
"video_count": int,
"view_count": int,
"description": str,
"published_at": str
}
```
3. **Comment Format**
```python
{
"author": str,
"text": str,
"like_count": int,
"published_at": str
}
```
## š¤ Contributing
1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request
## š License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## š Acknowledgments
- [FastMCP](https://github.com/fastmcp) for the MCP framework
- [YouTube Data API](https://developers.google.com/youtube/v3) for the API
- All contributors and users of this project
## š Support
For support, please:
1. Check the [documentation](docs/)
2. Open an [issue](https://github.com/yourusername/youtube-mcp-server/issues)
3. Contact the maintainers
## š Updates
Stay updated with the project:
- Watch the repository
- Check the [releases](https://github.com/yourusername/youtube-mcp-server/releases)
- Follow the [changelog](CHANGELOG.md)
## š Security
### Handling Sensitive Data
ā ļø **IMPORTANT**: Never commit sensitive files to the repository:
- `token.pickle`
- `client_secrets.json`
- `.env` files
- Any other credential files
These files are automatically ignored by `.gitignore`, but if you accidentally commit them:
1. Remove them from git tracking:
```bash
git rm --cached token.pickle
git rm --cached client_secrets.json
```
2. Revoke and regenerate any exposed credentials
3. Update your local `.env` file with new credentials
4. Never share or expose these files publicly
### Best Practices
1. Always use environment variables for sensitive data
2. Keep credentials in `.env` file (already in `.gitignore`)
3. Regularly rotate API keys and tokens
4. Use OAuth 2.0 for authentication
5. Monitor GitHub's secret scanning alerts
## š„ļø Claude Desktop Setup
### 1. Install Claude Desktop
1. **Download Claude Desktop:**
- Visit [Claude Desktop](https://claude.ai/download)
- Download the appropriate version for your OS:
- macOS: `.dmg` file
- Windows: `.exe` installer
- Linux: `.AppImage` or `.deb` package
2. **Install the Application:**
```bash
# macOS
# 1. Open the .dmg file
# 2. Drag Claude to Applications folder
# 3. Open from Applications
# Windows
# 1. Run the .exe installer
# 2. Follow the installation wizard
# 3. Launch from Start Menu
# Linux (Ubuntu/Debian)
sudo dpkg -i claude-desktop_*.deb # For .deb package
# OR
chmod +x Claude-*.AppImage # For AppImage
./Claude-*.AppImage
```
### 2. Configure MCP Client
1. **Open Claude Desktop Settings:**
- Click on the gear icon (āļø) or
- Use keyboard shortcut:
- macOS: `Cmd + ,`
- Windows/Linux: `Ctrl + ,`
2. **Add MCP Configuration:**
- Navigate to "MCP Settings" or "Advanced Settings"
- Add the following configuration:
```json
{
"mcpServers": {
"youtube_videos": {
"command": "uv",
"args": [
"--directory",
"<your base directory>/youtube-mcp-server",
"run",
"mcp_videos.py"
]
}
}
}
```
3. **Replace Path:**
- Replace `<your base directory>` with your actual project path
- Example for different OS:
```json
// macOS/Linux
"/Users/username/Documents/youtube-mcp-server"
// Windows
"C:\\Users\\username\\Documents\\youtube-mcp-server"
```
4. **Verify Configuration:**
```bash
# Test the MCP server path
cd "<your base directory>/youtube-mcp-server"
uv run mcp_videos.py
```
### 3. Using Claude with MCP
1. **Start Claude Desktop**
2. **Connect to MCP Server:**
- The server should start automatically
- You'll see a connection status indicator
- Available tools will be listed in the interface
3. **Test the Connection:**
```python
# Try a simple command
get_videos("python programming", max_results=5)
```
### Troubleshooting MCP Connection
1. **Server Won't Start:**
```bash
# Check if the path is correct
pwd # Should show your project directory
# Verify Python environment
which python # Should point to your virtual environment
# Check uv installation
uv --version
```
2. **Connection Issues:**
- Verify the server is running
- Check the configuration path
- Ensure all dependencies are installed
- Check the logs in Claude Desktop
3. **Common Errors:**
```bash
# Path not found
# Solution: Use absolute path in configuration
# Permission denied
# Solution: Check file permissions
chmod +x mcp_videos.py
# Module not found
# Solution: Verify virtual environment
source .venv/bin/activate # or appropriate activation command
```
