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:
- Download Python installer from python.org
- Run the installer
- Check "Add Python to PATH" during installation
- 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
- 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"
```
-
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" -
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" -
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)
```
- 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.jsonortoken.pickleto 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 localcredentials.json
Installation
- 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
- 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
- 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
- Create a
.envfile 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)
- 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)
- 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)
- 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)
- 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
- 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
}
- 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
- Fork the repository
- Create a feature branch
- Commit your changes
- Push to the branch
- Create a Pull Request
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🙏 Acknowledgments
- FastMCP for the MCP framework
- YouTube Data API for the API
- All contributors and users of this project
📞 Support
For support, please:
- Check the documentation
- Open an issue
- Contact the maintainers
🔄 Updates
Stay updated with the project:
- Watch the repository
- Check the releases
- Follow the changelog
🔒 Security
Handling Sensitive Data
⚠️ IMPORTANT: Never commit sensitive files to the repository:
token.pickleclient_secrets.json.envfiles- Any other credential files
These files are automatically ignored by .gitignore, but if you accidentally commit them:
-
Remove them from git tracking:
bash git rm --cached token.pickle git rm --cached client_secrets.json -
Revoke and regenerate any exposed credentials
- Update your local
.envfile with new credentials - Never share or expose these files publicly
Best Practices
- Always use environment variables for sensitive data
- Keep credentials in
.envfile (already in.gitignore) - Regularly rotate API keys and tokens
- Use OAuth 2.0 for authentication
- Monitor GitHub's secret scanning alerts
🖥️ Claude Desktop Setup
1. Install Claude Desktop
- Download Claude Desktop:
- Visit Claude Desktop
- Download the appropriate version for your OS:
- macOS:
.dmgfile - Windows:
.exeinstaller - Linux:
.AppImageor.debpackage
- macOS:
- 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
- Open Claude Desktop Settings:
- Click on the gear icon (⚙️) or
- Use keyboard shortcut:
- macOS:
Cmd + , - Windows/Linux:
Ctrl + ,
- macOS:
- 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" ] } } }
- Replace Path:
- Replace `` 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"
```
- 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
- Start Claude Desktop
- Connect to MCP Server:
- The server should start automatically
- You'll see a connection status indicator
- Available tools will be listed in the interface
- Test the Connection:
python # Try a simple command get_videos("python programming", max_results=5)
Troubleshooting MCP Connection
- 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
```
- Connection Issues:
- Verify the server is running
- Check the configuration path
- Ensure all dependencies are installed
- Check the logs in Claude Desktop
- 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
```
