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)

npm install -g youtube-mcp-server

Option 2: Install from source

# 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

   • 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

{
  "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:

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:

{
  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:

{
  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:

{
  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:

{
  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:

{
  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:

{
  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:

{
  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 → 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

npm run build

Watch Mode (auto-rebuild on changes)

npm run dev

Start Server Manually

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

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 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! ⭐