YouTube MCP Server

Last Updated: 2025-07-05

A Model Context Protocol (MCP) server implementation utilizing the YouTube Data API. It allows AI language models to interact with YouTube content through a standardized interface.

✅ YouTube Transcript Support: This server includes full transcript/caption functionality using the youtube-transcript-api Python package. Simply install Python dependencies and optionally configure the Python path - transcripts work seamlessly for videos with available captions.

Table of Contents

• Key Features
• OAuth Authentication (Private Playlists)
• Available Tools
• Quick Start
• Prerequisites
  • 1. Python Setup (Required for Transcript Functionality)
  • 2. YouTube Data API Setup
  • 3. OAuth Setup (For Private Playlists - Optional)
• Environment Configuration
• Troubleshooting
• Development
• System Requirements
• Security Considerations
• Attribution
• License

Key Features

Video Information

• Retrieve detailed video information (title, description, duration, statistics)
• Search for videos by keywords
• Get related videos based on a specific video
• Calculate and analyze video engagement ratios

✅ Transcript/Caption Management (Fully Functional)

• Retrieve video transcripts using the powerful youtube-transcript-api Python package
• Multi-language support with automatic language detection and fallback options
• Time-stamped captions for precise content reference and analysis
• Easy setup - just install Python dependencies and optionally set your Python path
• Works reliably for any video with available captions/transcripts

Channel Analysis

• View detailed channel statistics (subscribers, views, video count)
• Get top-performing videos from a channel
• Analyze channel growth and engagement metrics

Playlist Management

• Retrieve detailed playlist information
• Get all videos within a playlist
• Search for public playlists by keywords
• Get all public playlists from a specific channel

Trend Analysis

• View trending videos by region and category
• Compare performance metrics across multiple videos
• Discover popular content in specific categories

OAuth Authentication (Private Playlists)

Note: OAuth is only required if you want to access your private YouTube playlists. Public content works without authentication.

Authentication Steps

1. Ensure OAuth is configured (see Prerequisites section above)

2. Authenticate with Google:

   For npx users:

   npx yt-mcp-auth auth

   For local development:

   npm run auth

3. Handle the "Google hasn't verified this app" warning:

   • Click "Advanced"
   • Click "Go to [your app name] (unsafe)"
   • This is safe since you created the OAuth app yourself

4. Complete the OAuth flow:

   • Grant the requested permissions
   • You'll see a success message when authentication completes

5. Verify authentication:

   For npx users:

   npx yt-mcp-auth status

   For local development:

   npm run auth:status

Managing Authentication

Check status:

# npx users
npx yt-mcp-auth status

# Local development  
npm run auth:status

Revoke authentication:

# npx users
npx yt-mcp-auth revoke

# Local development
npm run auth:revoke

Once authenticated, you can access your private playlists using the getMyPlaylists tool.

Available Tools

The server provides the following MCP tools:

| Tool Name | Description | Required Parameters | |-----------|-------------|---------------------| | getVideoDetails | Get detailed information about multiple YouTube videos including metadata, statistics, and content details | videoIds (array) | | searchVideos | Search for videos based on a query string | query, maxResults (optional) | | getTranscripts | Retrieve transcripts for multiple videos | videoIds (array), lang (optional) | | getRelatedVideos | Get videos related to a specific video based on YouTube's recommendation algorithm | videoId, maxResults (optional) | | getChannelStatistics | Retrieve detailed metrics for multiple channels including subscriber count, view count, and video count | channelIds (array) | | getChannelTopVideos | Get the most viewed videos from a specific channel | channelId, maxResults (optional) | | getVideoEngagementRatio | Calculate engagement metrics for multiple videos (views, likes, comments, and engagement ratio) | videoIds (array) | | getTrendingVideos | Get currently popular videos by region and category | regionCode (optional), categoryId (optional), maxResults (optional) | | compareVideos | Compare statistics across multiple videos | videoIds (array) | | getPlaylistDetails | Get detailed information about a specific YouTube playlist | playlistId | | getPlaylistVideos | Retrieve all videos contained in a specific playlist | playlistId, maxResults (optional) | | searchPublicPlaylists | Search for public playlists based on a query string | query, maxResults (optional), channelId (optional) | | getChannelPlaylists | Get all public playlists from a specific channel | channelId, maxResults (optional) | | getMyPlaylists | Get your own playlists (including private ones) | maxResults (optional) | | checkOAuthStatus | Check if OAuth authentication is active | None |

Quick Start

Option 1: Use with npx (Recommended)

No installation required! Use directly with Claude Desktop:

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "yt-mcp"],
      "env": {
        "YOUTUBE_API_KEY": "YOUR_API_KEY_HERE",
        "YOUTUBE_TRANSCRIPT_LANG": "en"
      }
    }
  }
}

Option 2: Local Development

git clone https://github.com/space-cadet/yt-mcp.git
cd yt-mcp
npm install
npm run build

Prerequisites

1. 🐍 Python Setup (Required for Transcript Functionality)

✅ YouTube transcript functionality is fully supported and working!

The transcript feature uses the youtube-transcript-api Python package to reliably fetch transcripts from any video with available captions.

📋 Setup Steps:

1. Install Python (if not already installed):

   • Python 3.7 or higher is required
   • Download from python.org or use your system's package manager
   • Verify installation: python --version or python3 --version

2. Install the Python transcript package:

   pip install youtube-transcript-api

   Or if you use pip3:

   pip3 install youtube-transcript-api

3. Configure Python path (if needed):

   • Most users won't need this step - the server will automatically find python3
   • Only needed if you're using conda, virtual environments, or custom Python installations
   • Set PYTHON_PATH in your environment to point to your Python executable
   • Examples:
     • /Users/username/miniconda3/bin/python
     • /opt/homebrew/bin/python3
     • C:\Python39\python.exe (Windows)

🎯 That's it! Once Python and the package are installed, transcript functionality works immediately for any video with available captions.

2. YouTube Data API Setup

Step-by-step Google Cloud Console setup:

1. Create/Select a Project:

   • Go to Google Cloud Console
   • Click "Select a project" → "New Project"
   • Name your project (e.g., "YouTube MCP Server")
   • Click "Create"

2. Enable YouTube Data API v3:

   • In the sidebar, go to "APIs & Services" → "Library"
   • Search for "YouTube Data API v3"
   • Click on it and press "Enable"

3. Create API Key:

   • Go to "APIs & Services" → "Credentials"
   • Click "Create Credentials" → "API Key"
   • Copy the generated API key
   • (Optional) Click "Restrict Key" to limit it to YouTube Data API v3

3. OAuth Setup (For Private Playlists - Optional)

Only needed if you want to access private playlists:

1. Create OAuth 2.0 Credentials:
   • In "APIs & Services" → "Credentials"
   • Click "Create Credentials" → "OAuth 2.0 Client ID"
   • If prompted, configure the OAuth consent screen first:
     • Choose "External" user type
     • Fill in app name, user support email, developer contact
     • Add your email to test users
   • Choose "Web application" as application type
   • Add authorized redirect URI: http://localhost:3000/oauth2callback
   • Copy the Client ID and Client Secret

Environment Configuration

For npx Users

Add environment variables directly to your Claude Desktop MCP configuration:

Basic configuration (public content + transcripts):

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "yt-mcp"],
      "env": {
        "YOUTUBE_API_KEY": "YOUR_API_KEY_HERE",
        "YOUTUBE_TRANSCRIPT_LANG": "en"
      }
    }
  }
}

Note: This configuration includes full transcript functionality! Just ensure you have Python and youtube-transcript-api installed.

Configuration with custom Python path (for conda/virtual environments):

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "yt-mcp"],
      "env": {
        "YOUTUBE_API_KEY": "YOUR_API_KEY_HERE",
        "YOUTUBE_TRANSCRIPT_LANG": "en",
        "PYTHON_PATH": "/path/to/your/python"
      }
    }
  }
}

Note: Most users don't need PYTHON_PATH - only set this if you're using conda, virtual environments, or custom Python installations.

Full configuration (with OAuth and custom Python path):

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "yt-mcp"],
      "env": {
        "YOUTUBE_API_KEY": "YOUR_API_KEY_HERE",
        "YOUTUBE_TRANSCRIPT_LANG": "en",
        "PYTHON_PATH": "/path/to/your/python",
        "GOOGLE_OAUTH_CLIENT_ID": "YOUR_OAUTH_CLIENT_ID",
        "GOOGLE_OAUTH_CLIENT_SECRET": "YOUR_OAUTH_CLIENT_SECRET",
        "OAUTH_REDIRECT_URI": "http://localhost:3000/oauth2callback"
      }
    }
  }
}

For Local Development

Create a .env file in the project root:

# Required
YOUTUBE_API_KEY=your_youtube_api_key_here

# Optional
YOUTUBE_TRANSCRIPT_LANG=en
PYTHON_PATH=/path/to/your/python

# OAuth (for private playlists)
GOOGLE_OAUTH_CLIENT_ID=your_oauth_client_id
GOOGLE_OAUTH_CLIENT_SECRET=your_oauth_client_secret
OAUTH_REDIRECT_URI=http://localhost:3000/oauth2callback

Local development MCP configuration:

{
  "mcpServers": {
    "youtube": {
      "command": "node",
      "args": ["/path/to/yt-mcp/dist/index.js"]
    }
  }
}

Troubleshooting

Common Issues

"Error: YOUTUBE_API_KEY environment variable is not set"

• Ensure you've added your YouTube API key to the MCP configuration
• Verify the API key is valid and has YouTube Data API v3 enabled

"Google hasn't verified this app" warning during OAuth

• This is expected for personal OAuth apps
• Click "Advanced" → "Go to [app name] (unsafe)" to continue
• This is safe since you created the OAuth credentials yourself

"OAuth authentication required" error

• Run the authentication command: npx yt-mcp-auth auth (or npm run auth for local)
• Make sure OAuth credentials are properly configured in your environment

"invalid_token" error during auth revocation

• This can happen if tokens are already expired
• The command will still clean up local authentication state
• You can safely re-authenticate after this error

🐍 Transcript functionality troubleshooting

✅ Good news: Transcript functionality is fully working and battle-tested! Most issues are simple setup problems.

• "ModuleNotFoundError: No module named 'youtube_transcript_api'":

  • Solution: Install the Python package: pip install youtube-transcript-api
  • If using conda/virtual environment, ensure the package is installed in that specific environment
  • Verify with: python -c "import youtube_transcript_api; print('Package installed successfully!')"

• "Failed to start Python process" or Python not found:

  • Solution: Set PYTHON_PATH environment variable to point to your Python executable
  • Find your Python path: which python3 (macOS/Linux) or where python (Windows)
  • Add to MCP config: "PYTHON_PATH": "/path/to/your/python"
  • Examples:
    • "/usr/bin/python3" (system Python)
    • "/Users/username/miniconda3/bin/python" (conda)
    • "C:\\Python39\\python.exe" (Windows)

• Empty transcript results:

  • This is normal! Some videos don't have transcripts available
  • Try popular videos (like TED talks, educational content) which usually have captions
  • Test with a known working video to verify functionality
  • The transcript API will return empty results for videos without captions

• Transcript language issues:

  • Set YOUTUBE_TRANSCRIPT_LANG to your preferred language (e.g., "en", "es", "fr")
  • The API will automatically fall back to available languages if your preference isn't available

MCP server not responding

• Verify Node.js version is 18.0.0 or higher
• Check that the YouTube API key is valid
• For local development, ensure you've run npm run build

Getting Help

If you encounter issues:

1. Check the troubleshooting section above
2. Verify your API key and OAuth setup
3. Create an issue on GitHub

Development

Local Development Setup

# Clone and setup
git clone https://github.com/space-cadet/yt-mcp.git
cd yt-mcp
npm install

# Create .env file with your credentials
cp .env.example .env
# Edit .env with your API keys

# Development commands
npm run dev      # Run in development mode with auto-reload
npm run build    # Build TypeScript to JavaScript  
npm run start    # Run built version
npm test         # Run tests
npm run lint     # Lint code

Project Structure

src/
├── index.ts              # Main MCP server
├── auth-cli.ts           # OAuth authentication CLI
├── functions/
│   ├── videos.ts         # Video-related API functions
│   └── playlists.ts      # Playlist-related API functions
└── utils/
    ├── oauth.ts          # OAuth token management
    ├── oauth-routes.ts   # OAuth callback server
    └── cli-auth.ts       # CLI authentication flow

System Requirements

• Node.js 18.0.0 or higher
• Internet connection for YouTube API access
• Port 3000 available for OAuth callback (when using OAuth)

Security Considerations

• Never commit API keys or OAuth secrets to version control
• Use environment variables for all sensitive configuration
• Set usage quotas on your Google Cloud API key to prevent abuse
• OAuth tokens are stored locally in tokens.json - keep this file secure
• Consider revoking OAuth access when no longer needed

Attribution

This project is forked from youtube-data-mcp-server by icraft2170. Special thanks to the original author for creating the foundation of this YouTube MCP server implementation.

License

This project is licensed under the MIT License. See the LICENSE file for details.