youtube-mcp

aardeshir/youtube-mcp

3.3

If you are the rightful owner of youtube-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

A Model Context Protocol (MCP) server for YouTube API integration, enabling video search, playlist management, and direct interaction with YouTube through Claude Desktop or other MCP clients.

YouTube MCP Server

A Model Context Protocol (MCP) server for YouTube API integration. Search videos, manage playlists, and interact with YouTube directly through Claude Desktop or other MCP clients.

Features

  • 🔍 Search YouTube videos
  • 📋 Create and manage playlists
  • ➕ Add videos to playlists
  • 📝 List user playlists
  • 🗑️ Delete playlists

Prerequisites

  • Node.js 18 or higher
  • YouTube Data API v3 access
  • Google Cloud Console account

Installation

Option 1: Install from npm (Recommended)

npm install -g @a.ardeshir/youtube-mcp

Option 2: Install from GitHub

git clone https://github.com/aardeshir/youtube-mcp.git
cd youtube-mcp
npm install

Setup

1. Set Up YouTube API

Step 1: Create a Google Cloud Project
  1. Go to Google Cloud Console
  2. Create a new project or select existing one
  3. Note your Project ID
Step 2: Enable YouTube Data API v3
  1. In Google Cloud Console, go to "APIs & Services" > "Library"
  2. Search for "YouTube Data API v3"
  3. Click on it and press "Enable"

Common Issue: If you see "YouTube Data API v3 has not been used in project before or it is disabled", wait 2-3 minutes after enabling for it to propagate.

Step 3: Create OAuth 2.0 Credentials
  1. Go to "APIs & Services" > "Credentials"
  2. Click "+ CREATE CREDENTIALS" > "OAuth client ID"
  3. If prompted, configure OAuth consent screen:
    • Choose "External" (or "Internal" for Workspace)
    • Fill required fields (app name, support email)
    • Add your email as a test user
    • For scopes, add: https://www.googleapis.com/auth/youtube
  4. For Application type, select "Web application"
  5. Add authorized redirect URI: http://localhost:8080/callback
  6. Save and note your Client ID and Client Secret
Step 4: Get API Key (Optional - for read-only access)
  1. Go to "APIs & Services" > "Credentials"
  2. Click "+ CREATE CREDENTIALS" > "API key"
  3. Restrict the key to YouTube Data API v3

2. Authenticate

Run the OAuth setup wizard:

If installed via npm:

youtube-mcp-setup

If installed from GitHub:

npm run auth-setup

This will:

  1. Prompt for your Client ID and Client Secret
  2. Open browser for Google authorization
  3. Generate refresh token automatically
  4. Create .env file with your credentials

3. Configure Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on Mac):

If installed via npm:

{
  "mcpServers": {
    "youtube-mcp": {
      "command": "npx",
      "args": ["-y", "@a.ardeshir/youtube-mcp"],
      "env": {
        "YOUTUBE_API_KEY": "your-api-key",
        "YOUTUBE_CLIENT_ID": "your-client-id",
        "YOUTUBE_CLIENT_SECRET": "your-client-secret",
        "YOUTUBE_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

If installed from GitHub:

{
  "mcpServers": {
    "youtube-mcp": {
      "command": "node",
      "args": ["/path/to/youtube-mcp/index.js"],
      "env": {
        "YOUTUBE_API_KEY": "your-api-key",
        "YOUTUBE_CLIENT_ID": "your-client-id",
        "YOUTUBE_CLIENT_SECRET": "your-client-secret",
        "YOUTUBE_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

Usage Examples

Search Videos

Search YouTube for "piano tutorials"

Create Playlist

Create a YouTube playlist called "My Favorites"

List Playlists

Show my YouTube playlists

Troubleshooting

"YouTube Data API v3 has not been used in project before"

  • Ensure API is enabled in Google Cloud Console
  • Wait 2-3 minutes for changes to propagate
  • Check you're using correct project

"Invalid Credentials" error

  • Verify OAuth consent screen is configured
  • Ensure test user email is added
  • Check redirect URI matches exactly: http://localhost:8080/callback

MCP not connecting in Claude Desktop

  • Check all environment variables are set
  • Restart Claude Desktop after config changes
  • Verify Node.js path is correct

"Quota exceeded" error

  • YouTube API has daily quotas
  • Check Google Cloud Console for usage
  • Consider requesting quota increase

Security Notes

  • Never commit .env file to version control
  • Keep your refresh token secure
  • Use OAuth for production, API key only for testing
  • Regularly rotate credentials

Contributing

Contributions welcome! Please:

  1. Fork the repository
  2. Create feature branch
  3. Submit pull request

License

MIT - See LICENSE file

Support

For issues and questions:

Acknowledgments

Built with: