youtube-content-management-mcp

YouTube Content Management MCP Server

A Model Context Protocol (MCP) server that provides YouTube Data API v3 integration for content discovery and analytics. This server enables AI assistants to search for YouTube videos, channels, playlists, and retrieve detailed metrics for videos, channels, and playlists.

Features

Current Tools

• 🎥 search_videos: Search YouTube for videos with advanced filtering options, including view count, like count, and comment count.
• 📺 search_channels: Find YouTube channels based on search queries, including subscriber count, video count, and total view count.
• 📋 search_playlists: Search YouTube for playlists based on search queries.
• 📊 get_video_metrics: Retrieve statistics (views, likes, comments) for a specific video by ID.
• 📈 get_channel_metrics: Retrieve statistics (subscribers, total views, video count) for a specific channel by ID.
• 📑 get_playlist_metrics: Retrieve statistics (item count, total views) for a specific playlist by ID.

Planned Features

• Playlist creation and management
• Comment retrieval and analysis
• Video upload and management (with proper authentication)
• Trending videos by region
• Video transcription access

Prerequisites

• Python 3.8 or higher
• YouTube Data API v3 key
• VSCode with MCP extension (for VSCode usage)
• Required Python packages: google-api-python-client, python-dotenv, pydantic

Getting Your YouTube API Key

1. Go to the Google Cloud Console
2. Create a new project or select an existing one
3. Enable the YouTube Data API v3:
   • Navigate to "APIs & Services" > "Library"
   • Search for "YouTube Data API v3"
   • Click on it and press "Enable"
4. Create credentials:
   • Go to "APIs & Services" > "Credentials"
   • Click "Create Credentials" > "API Key"
   • Copy the generated API key
5. (Recommended) Restrict the API key:
   • Click on the API key to edit it
   • Under "API restrictions", select "Restrict key"
   • Choose "YouTube Data API v3"
   • Save the changes

Installation

1. Clone or download this repository

   git clone https://github.com/NastyRunner13/youtube-content-management-mcp
   cd youtube-content-management-mcp
   

2. Install dependencies

   pip install -r requirements.txt
   

   Or if using uv:

   uv install
   

3. Set up your environment (Optional)
   Create a .env file in the project root:

   YOUTUBE_API_KEY=your_youtube_api_key_here
   

Usage

With VSCode (Recommended)

1. Install the MCP extension in VSCode

2. Configure the MCP server by adding this to your VSCode settings.json:

   {
     "mcp.servers": {
       "youtube-content-management": {
         "command": "python",
         "args": [
           "/path/to/youtube-content-management-mcp/main.py"
         ],
         "env": {
           "YOUTUBE_API_KEY": "your_youtube_api_key_here"
         }
       }
     }
   }
   

   Alternative using uv:

   {
     "mcp.servers": {
       "youtube-content-management": {
         "command": "uv",
         "args": [
           "--directory",
           "/path/to/youtube-content-management-mcp",
           "run",
           "main.py"
         ],
         "env": {
           "YOUTUBE_API_KEY": "your_youtube_api_key_here"
         }
       }
     }
   }
   

3. Restart VSCode or reload the window

4. Use the tools through the MCP panel or by asking your AI assistant

With Claude Desktop

Add this configuration to your Claude Desktop config file:

Windows: %APPDATA%/Claude/claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "youtube-content-management": {
      "command": "python",
      "args": ["/path/to/youtube-content-management-mcp/main.py"],
      "env": {
        "YOUTUBE_API_KEY": "your_youtube_api_key_here"
      }
    }
  }
}

With Other MCP Clients

The server implements the standard MCP protocol and should work with any compatible MCP client. Refer to your client's documentation for configuration instructions.

Available Tools

search_videos

Search YouTube for videos with advanced filtering options, including metrics like view count, like count, and comment count.

Parameters:

• query (string, required): Search query
• max_results (integer, optional): Maximum number of results (1-50, default: 25)
• order (string, optional): Sort order - "relevance", "date", "rating", "viewCount" (default: "relevance")
• duration (string, optional): Video duration - "medium", "long" (default: "medium")
• published_after (string, optional): RFC 3339 timestamp (e.g., "2023-01-01T00:00:00Z")

Example usage:

Search for Python tutorials uploaded in the last year, sorted by view count

search_channels

Find YouTube channels based on search queries, including metrics like subscriber count, video count, and total view count.

Parameters:

• query (string, required): Search query for channels
• max_results (integer, optional): Maximum number of results (1-50, default: 25)
• published_after (string, optional): RFC 3339 timestamp (e.g., "2023-01-01T00:00:00Z")

Example usage:

Find coding tutorial channels

search_playlists

Search YouTube for playlists based on search queries.

Parameters:

• query (string, required): Search query for playlists
• max_results (integer, optional): Maximum number of results (1-50, default: 25)
• published_after (string, optional): RFC 3339 timestamp (e.g., "2023-01-01T00:00:00Z")

Example usage:

Find playlists about machine learning

get_video_metrics

Retrieve statistics for a specific YouTube video, including view count, like count, and comment count.

Parameters:

• video_id (string, required): The YouTube video ID

Example usage:

Get metrics for the video with ID dQw4w9WgXcQ

get_channel_metrics

Retrieve statistics for a specific YouTube channel, including subscriber count, total view count, and video count.

Parameters:

• channel_id (string, required): The YouTube channel ID

Example usage:

Get metrics for the channel with ID UC_x5XG1OV2P6uZZ5FSM9Ttw

get_playlist_metrics

Retrieve statistics for a specific YouTube playlist, including item count and total view count of all videos.

Parameters:

• playlist_id (string, required): The YouTube playlist ID

Example usage:

Get metrics for the playlist with ID PL-osiE80TeTt2d9bfVyTiXJA-UTHn6WwU

Example Interactions

Once the MCP server is configured, you can interact with it through your AI assistant:

Video Search with Metrics:

"Search for machine learning tutorials from the last 6 months, sorted by view count, and show view counts"

Channel Discovery with Metrics:

"Find top cooking channels on YouTube with their subscriber counts"

Playlist Search:

"Show me playlists about Python programming"

Video Metrics:

"Get the view count and like count for the video with ID dQw4w9WgXcQ"

Channel Metrics:

"What are the subscriber count and total views for the channel UC_x5XG1OV2P6uZZ5FSM9Ttw?"

Playlist Metrics:

"How many videos and total views are in the playlist PL-osiE80TeTt2d9bfVyTiXJA-UTHn6WwU?"

Input Validation

All tools use Pydantic for robust input validation, ensuring:

• Required fields (e.g., query, video_id) are provided and non-empty.
• Numeric fields (e.g., max_results) are within valid ranges (1-50).
• String fields (e.g., order, duration) match allowed values.
• Timestamps (e.g., published_after) follow RFC 3339 format.

Invalid inputs result in clear error messages, improving reliability and user experience.

Security Notes

• Never commit your API key to version control
• Consider using environment variables instead of hardcoding API keys
• Regularly rotate your API keys
• Monitor your API usage in Google Cloud Console
• Set up API key restrictions to limit usage to YouTube Data API v3

Troubleshooting

Common Issues

1. "YouTube API key is not set"

   • Ensure your API key is properly configured in the environment variables
   • Check that the key is valid and has YouTube Data API v3 enabled

2. "quotaExceeded" errors

   • You've hit your daily API quota limit (default: 10,000 units)
   • Wait until the quota resets (daily) or increase your quota in Google Cloud Console
   • Note: Metrics tools and search tools with metrics may consume more quota due to multiple API calls

3. "keyInvalid" errors

   • Your API key is invalid or has been revoked
   • Generate a new API key and update your configuration

4. "Invalid input arguments" errors

   • Check the Pydantic error message for details (e.g., missing query, invalid order)
   • Ensure inputs match the tool's parameter requirements

5. MCP server not starting

   • Check that all dependencies (google-api-python-client, python-dotenv, pydantic) are installed
   • Verify the Python path in your configuration is correct
   • Check the MCP extension logs for detailed error messages

Debug Mode

To enable debug logging, add this to your environment:

"env": {
  "YOUTUBE_API_KEY": "your_key_here",
  "DEBUG": "true"
}

Contributing

We welcome contributions! Areas where you can help:

• Additional YouTube API endpoints (comments, transcriptions)
• Optimizing API quota usage (e.g., batching metrics calls)
• Enhancing Pydantic validation rules
• Performance optimizations
• Documentation improvements
• Testing and bug reports

API Limits

• YouTube Data API v3: 10,000 units per day (default)
• Search operations: 100 units per request
• List operations (videos, channels, playlists): 1 unit per request
• Playlist items: 5 units per request
• Rate limiting: Be mindful of making too many requests in quick succession, especially with metrics tools

Support

• Create an issue for bugs or feature requests
• Check the YouTube Data API documentation for API-specific questions
• Review MCP protocol documentation for integration issues
• Refer to Pydantic documentation for validation-related questions