# YouTube MCP Server
> An MCP (Model Context Protocol) server that enables YouTube content browsing and summarization using the YouTube Data API v3.
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)
## 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](#prerequisites)
- [Installation](#installation)
- [Getting a YouTube API Key](#getting-a-youtube-api-key)
- [Configuration](#configuration)
- [Usage](#usage)
- [Available Tools](#available-tools)
- [Examples](#examples)
- [API Quota Management](#api-quota-management)
- [Contributing](#contributing)
- [License](#license)
## Prerequisites
- **Node.js** v18 or higher ([Download](https://nodejs.org/))
- **YouTube Data API v3 key** (free, see [Getting a YouTube API Key](#getting-a-youtube-api-key))
- **MCP-compatible client** (e.g., [Claude Code](https://claude.com/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
1. **Go to [Google Cloud Console](https://console.cloud.google.com)**
- Sign in with your Gmail account
2. **Create a New Project**
- Click "Select a project" → "New Project"
- Name it (e.g., "YouTube MCP Server")
- Click "Create"
3. **Enable YouTube Data API v3**
- Use the search bar to find "YouTube Data API v3"
- Click on it and press "Enable"
4. **Create API Key**
- Go to "APIs & Services" → "Credentials"
- Click "Create Credentials" → "API key"
- Copy the generated API key
5. **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
1. **Use transcripts when possible** - They don't use API quota
2. **Cache results** - Store frequently accessed data locally
3. **Combine operations** - Get channel info with videos in one call
4. **Monitor usage** - Check quota in Google Cloud Console
5. **Request quota increase** - Contact Google if you need more
### Checking Your Quota
Visit [Google Cloud Console](https://console.cloud.google.com) → 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](https://www.npmjs.com/package/@modelcontextprotocol/sdk)** - MCP protocol implementation
- **[googleapis](https://www.npmjs.com/package/googleapis)** - Official YouTube Data API v3 client
- **[youtube-transcript](https://www.npmjs.com/package/youtube-transcript)** - Web scraping for public transcripts
- **[TypeScript](https://www.typescriptlang.org/)** - Type-safe development
- **[Node.js](https://nodejs.org/)** - 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](CONTRIBUTING.md) for guidelines.
### Quick Contribution Steps
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## Security
Please see [SECURITY.md](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](LICENSE) file for details.
## Acknowledgments
- Built with the [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic
- Uses the [YouTube Data API v3](https://developers.google.com/youtube/v3) by Google
- Inspired by the MCP community
## Support
- **Issues**: [GitHub Issues](https://github.com/anirudhyadavMS/youtube_mcp/issues)
- **Discussions**: [GitHub Discussions](https://github.com/anirudhyadavMS/youtube_mcp/discussions)
- **MCP Documentation**: [modelcontextprotocol.io](https://modelcontextprotocol.io/)
## Related Projects
- [MCP Servers Repository](https://github.com/modelcontextprotocol/servers) - Official MCP servers
- [Claude Code](https://claude.com/claude-code) - AI coding assistant with MCP support
- [Cline](https://github.com/cline/cline) - Another MCP-compatible client
---
Made with ❤️ for the MCP community
**Star this repo if you find it useful!** ⭐
