YouTube MCP Server
> An MCP (Model Context Protocol) server that enables YouTube content browsing and summarization using the YouTube Data API v3.
Features
- 🔍 Video Search: Search YouTube for videos by keyword with customizable sorting
- 📊 Video Details: Get comprehensive metadata about any video (views, likes, duration, tags)
- 📝 Video Transcripts: Fetch video transcripts/captions for summarization and analysis
- 👤 Channel Information: Get channel stats, subscriber counts, and recent videos
- 🎬 Channel Videos: List all videos from a specific channel with sorting options
- 📋 Playlist Information: Get playlist metadata and video counts
- 🎵 Playlist Videos: List all videos in a playlist with positions
Why Use This?
- AI-Powered Analysis: Perfect for AI assistants like Claude to analyze YouTube content
- Cross-Platform: Works with any MCP-compatible client (Claude Code, Cline, etc.)
- Comprehensive: Combines YouTube Data API v3 with transcript scraping
- Free Tier Friendly: Optimized for Google's free API quota (10,000 units/day)
- Type-Safe: Built with TypeScript for reliability
Table of Contents
- Prerequisites
- Installation
- Getting a YouTube API Key
- Configuration
- Usage
- Available Tools
- Examples
- API Quota Management
- Contributing
- License
Prerequisites
- Node.js v18 or higher (Download)
- YouTube Data API v3 key (free, see Getting a YouTube API Key)
- MCP-compatible client (e.g., Claude Code)
Installation
Option 1: Install from npm (coming soon)```bash
npm install -g youtube-mcp-server
### Option 2: Install from source```bash
# Clone the repository
git clone https://github.com/anirudhyadavMS/youtube_mcp.git
cd youtube-mcp-server
# Install dependencies
npm install
# Build the project
npm run build
Getting a YouTube API Key
You can get a free YouTube Data API key with any Gmail account (no credit card required).
Step-by-Step Guide
-
Go to Google Cloud Console
- Sign in with your Gmail account -
Create a New Project
- Click "Select a project" → "New Project"
- Name it (e.g., "YouTube MCP Server")
- Click "Create" -
Enable YouTube Data API v3
- Use the search bar to find "YouTube Data API v3"
- Click on it and press "Enable" -
Create API Key
- Go to "APIs & Services" → "Credentials"
- Click "Create Credentials" → "API key"
- Copy the generated API key -
Restrict Your API Key (Recommended for security)
- Click on the API key you just created
- Under "API restrictions", select "Restrict key"
- Choose "YouTube Data API v3" only
- Click "Save"
Free Tier Limits
- Daily Quota: 10,000 units per day
- Search: 100 units per request (~100 searches/day)
- Video Details: 1 unit per request (~10,000 requests/day)
- Transcripts: Uses web scraping (no quota cost)
Configuration
For Claude Code
Add this to your MCP configuration file:
macOS/Linux: ~/.config/claude-code/mcp_config.json or ~/.mcp.json
Windows: C:\Users\YOUR-USERNAME\.config\claude-code\mcp_config.json or `C:\Users\YOUR-USERNAME.mcp.json````json
{
"mcpServers": {
"youtube": {
"type": "stdio",
"command": "node",
"args": ["/absolute/path/to/youtube-mcp-server/dist/server.js"],
"env": {
"YOUTUBE_API_KEY": "YOUR_API_KEY_HERE"
}
}
}
}
### For Other MCP Clients
Configure using stdio transport with:
- **Command**: `node`
- **Args**: Path to `dist/server.js`
- **Environment**: `YOUTUBE_API_KEY` with your API key
### Environment Variables
Alternatively, create a `.env` file in the project root:```bash
YOUTUBE_API_KEY=your_api_key_here
Usage
Once configured, restart your MCP client (e.g., Claude Code). The YouTube tools will be automatically available.
Quick Start Examples
Ask your AI assistant:```
"Search YouTube for 'python tutorial' and show me the top 5 videos"
"Get the transcript for video dQw4w9WgXcQ and summarize it"
"Find the most popular videos from the Fireship channel"
``````
"What are the videos in the 'Learn Python' playlist?"
## Available Tools
### 1. `search_youtube`
Search YouTube for videos by keyword.
**Parameters:**```typescript
{
query: string // Required: Search term
maxResults?: number // Optional: 1-50, default 10
order?: string // Optional: "relevance" | "date" | "viewCount" | "rating"
}
Returns: Array of videos with ID, title, channel, thumbnail, description, views, publish date
2. get_video_details
Get comprehensive metadata about a specific video.
Parameters:```typescript
{
videoId: string // Required: YouTube video ID (e.g., "dQw4w9WgXcQ")
}
**Returns:** Detailed video object with title, description, duration, views, likes, tags, category, thumbnails
---
### 3. `get_video_transcript`
Fetch the transcript/captions for a YouTube video.
**Parameters:**```typescript
{
videoId: string // Required: YouTube video ID
language?: string // Optional: Language code, default "en"
includeTimestamps?: boolean // Optional: Include timestamps, default true
}
Returns: Full transcript text with optional timestamps
Note: Only works for videos with captions enabled.
4. get_channel_info
Get detailed information about a YouTube channel.
Parameters:```typescript
{
channelId: string // Required: YouTube channel ID
includeVideos?: boolean // Optional: Include recent videos, default false
}
**Returns:** Channel name, description, subscriber count, view count, video count, recent videos
---
### 5. `get_channel_videos`
List videos from a specific YouTube channel.
**Parameters:**```typescript
{
channelId: string // Required: YouTube channel ID
maxResults?: number // Optional: 1-50, default 25
order?: string // Optional: "date" | "viewCount" | "title"
}
Returns: Array of video objects from the channel
6. get_playlist_info
Get information about a YouTube playlist.
Parameters:```typescript
{
playlistId: string // Required: YouTube playlist ID
}
**Returns:** Playlist title, description, video count, channel, thumbnail
---
### 7. `get_playlist_videos`
List all videos in a YouTube playlist.
**Parameters:**```typescript
{
playlistId: string // Required: YouTube playlist ID
maxResults?: number // Optional: 1-50, default 50
}
Returns: Array of video objects with playlist positions
Examples
Example 1: Finding Trending Videos```
User: "Search for 'AI news' on YouTube, sorted by view count, show me 10 results"
AI uses: search_youtube
{
"query": "AI news",
"maxResults": 10,
"order": "viewCount"
}
### Example 2: Video Analysis```
User: "Get the transcript for video dQw4w9WgXcQ and summarize the main topics"
AI uses: get_video_transcript
{
"videoId": "dQw4w9WgXcQ",
"language": "en",
"includeTimestamps": false
}
AI then summarizes the transcript content.
Example 3: Channel Deep Dive```
User: "Tell me about the Fireship channel and show me their recent videos"
AI uses: get_channel_info
{
"channelId": "UCsBjURrPoezykLs9EqgamOA",
"includeVideos": true
}
### Example 4: Playlist Exploration```
User: "What videos are in this playlist: PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf"
AI uses: get_playlist_videos
{
"playlistId": "PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf",
"maxResults": 50
}
API Quota Management
The YouTube Data API has a daily quota limit. Here's how to manage it:
Quota Costs
| Operation | Quota Cost | Requests/Day (10,000 limit) |
|---|---|---|
| Search | 100 units | ~100 searches |
| Video Details | 1 unit | ~10,000 requests |
| Channel Info | 1 unit | ~10,000 requests |
| Playlist Info | 1 unit | ~10,000 requests |
| Transcripts | 0 units | Unlimited (web scraping) |
Tips to Conserve Quota
- Use transcripts when possible - They don't use API quota
- Cache results - Store frequently accessed data locally
- Combine operations - Get channel info with videos in one call
- Monitor usage - Check quota in Google Cloud Console
- Request quota increase - Contact Google if you need more
Checking Your Quota
Visit Google Cloud Console → APIs & Services → Dashboard → YouTube Data API v3
Project Structure```
youtube-mcp-server/
├── src/
│ ├── server.ts # Main MCP server implementation
│ ├── youtube-api.ts # YouTube Data API wrapper
│ ├── transcript.ts # Transcript fetching (web scraping)
│ └── types.ts # TypeScript type definitions
├── dist/ # Compiled JavaScript (generated)
├── package.json # Dependencies and scripts
├── tsconfig.json # TypeScript configuration
├── .env.example # API key template
├── LICENSE # MIT License
├── CONTRIBUTING.md # Contribution guidelines
├── SECURITY.md # Security best practices
└── README.md # This file
## Development
### Build```bash
npm run build
Watch Mode (auto-rebuild on changes)```bash
npm run dev
### Start Server Manually```bash
npm start
Error Handling
The server handles common errors gracefully:
| Error | Message |
|---|---|
| Missing API Key | Clear setup instructions |
| Quota Exceeded | Helpful message about daily limits |
| Invalid Video/Channel/Playlist ID | User-friendly error |
| Transcript Unavailable | "No transcript available for this video" |
| Network Errors | Automatic error reporting |
Technology Stack
- @modelcontextprotocol/sdk - MCP protocol implementation
- googleapis - Official YouTube Data API v3 client
- youtube-transcript - Web scraping for public transcripts
- TypeScript - Type-safe development
- Node.js - Runtime environment
Limitations
- API quota limits (10,000 units/day on free tier)
- Transcripts only available for videos with captions enabled
- Some private or restricted videos may not be accessible
- No support for OAuth-only features (comments, ratings, personal data)
- Maximum 50 results per request (YouTube API limitation)
Roadmap
Future enhancements being considered:
- [ ] Caching layer to reduce API quota usage
- [ ] Support for YouTube Shorts metadata
- [ ] Batch operations for multiple videos
- [ ] Live stream detection and metadata
- [ ] Comment fetching (requires OAuth)
- [ ] Video category lookup
- [ ] Trending videos by region
- [ ] Unit and integration tests
Contributing
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
Quick Contribution Steps
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Security
Please see SECURITY.md for security best practices and how to report vulnerabilities.
Key Security Tips:
- Never commit your API key to version control
- Restrict your API key to YouTube Data API v3 only
- Monitor your API usage regularly
- Rotate API keys periodically
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgments
- Built with the Model Context Protocol by Anthropic
- Uses the YouTube Data API v3 by Google
- Inspired by the MCP community
Support
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- MCP Documentation: modelcontextprotocol.io
Related Projects
- MCP Servers Repository - Official MCP servers
- Claude Code - AI coding assistant with MCP support
- Cline - Another MCP-compatible client
Made with ❤️ for the MCP community
Star this repo if you find it useful! ⭐