CLAUDE.md•2.77 kB
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
This is a YouTube Search MCP (Model Context Protocol) Server built with Python and FastMCP. It provides YouTube search functionality through the YouTube Data API v3, enabling AI applications to search videos, channels, and playlists with comprehensive filtering options.
## Development Commands
### Setup and Installation
```bash
# Install dependencies
pip install -r requirements.txt
# Set up YouTube API key (required)
export YOUTUBE_API_KEY="your_youtube_api_key_here"
```
### Running the Server
```bash
# Run the main MCP server
python youtube_search_mcp.py
# Run server tests
python test_server.py
python test_tools.py
```
### Testing
```bash
# Basic server connectivity test
python test_server.py
# Tool functionality tests
python test_tools.py
```
## Architecture
### Core Components
- **`youtube_search_mcp.py`** - Main MCP server implementation with YouTubeSearchAPI class
- **`YouTubeSearchAPI`** - Handles YouTube Data API v3 communication and request formatting
- **FastMCP Server** - Implements MCP protocol with tool decorators and resource handlers
- **Tool Functions** - 5 specialized search tools with different filtering capabilities
### Available MCP Tools
1. **`search_youtube`** - General search with comprehensive filtering
2. **`search_youtube_videos`** - Video-specific search with video filters
3. **`search_youtube_channels`** - Channel-specific search
4. **`search_youtube_playlists`** - Playlist-specific search
5. **`search_youtube_by_channel`** - Search within a specific channel
### Search Parameters
- Query filtering with content type specification
- Result ordering (relevance, date, rating, viewCount, title)
- Video duration filtering (short, medium, long)
- Video quality filtering (high, standard)
- Geographic region and language filtering
- Date range filtering (published_after/before)
- Pagination support with tokens
## Environment Requirements
- **Python 3.x** with venv virtual environment
- **YouTube Data API v3 key** - Set as `YOUTUBE_API_KEY` environment variable
- **Dependencies**: fastmcp>=2.0.0, requests>=2.31.0
## API Integration
- Uses YouTube Data API v3 search endpoint
- Implements quota-aware requests (100 units per search)
- Supports up to 50 results per request
- Handles API authentication and comprehensive error responses
- Daily quota: 10,000 units (~100 searches per day)
## Configuration Files
- **`mcp.json`** - MCP server configuration for Claude integration
- **`server-info.json`** - Server metadata and tool definitions
- **`requirements.txt`** - Python dependencies
- **`docs/`** - Contains FastMCP and YouTube API documentation