# YouTube MCP Server

> An MCP (Model Context Protocol) server that enables YouTube content browsing and summarization using the YouTube Data API v3.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](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!** ⭐