py mcp youtube toolbox

An MCP server that provides AI assistants with powerful tools to interact with YouTube, including video searching, transcript extraction, comment retrieval, and more.

Overview

py-mcp-youtube-toolbox provides the following YouTube-related functionalities:

• Search YouTube videos with advanced filtering options
• Get detailed information about videos and channels
• Retrieve video comments with sorting options
• Extract video transcripts and captions in multiple languages
• Find related videos for a given video
• Get trending videos by region
• Generate summaries of video content based on transcripts
• Advanced transcript analysis with filtering, searching, and multi-video capabilities

Table of Contents

• Prerequisites
• Installation
• Configure MCP Settings
• Tools Documentation
• Video Tools
• Channel Tools
• Transcript Tools
• Prompt Tools
• Resource Tools
• Development
• License

Prerequisites

1. Python: Install Python 3.12 or higher
2. YouTube API Key:
3. Go to Google Cloud Console
4. Create a new project or select an existing one
5. Enable the YouTube Data API v3:
   1. Go to "APIs & Services" > "Library"
   2. Search for and enable "YouTube Data API v3"
6. Create credentials:
   1. Go to "APIs & Services" > "Credentials"
   2. Click "Create Credentials" > "API key"
   3. Note down your API key

Installation

Git Clone

git clone https://github.com/jikime/py-mcp-youtube-toolbox.git
cd py-mcp-youtube-toolbox

Configuration

1. Install UV package manager:

   curl -LsSf https://astral.sh/uv/install.sh | sh

2. Create and activate virtual environment:

   uv venv -p 3.12
   source .venv/bin/activate  # On MacOS/Linux
   # or
   .venvScriptsactivate  # On Windows

3. Install dependencies:

   uv pip install -r requirements.txt

4. Environment variables:

   cp env.example .env
   vi .env
   # Update with your YouTube API key
   YOUTUBE_API_KEY=your_youtube_api_key

Using Docker

1. Build the Docker image:

   docker build -t py-mcp-youtube-toolbox .

2. Run the container:

   docker run -e YOUTUBE_API_KEY=your_youtube_api_key py-mcp-youtube-toolbox

Using Local

1. Run the server:

   mcp run server.py

2. Run the MCP Inspector:

   mcp dev server.py

Configure MCP Settings

Add the server configuration to your MCP settings file:

Claude desktop app

1. To install automatically via Smithery:

npx -y @smithery/cli install @jikime/py-mcp-youtube-toolbox --client claude

1. To install manually open ~/Library/Application Support/Claude/claude_desktop_config.json

Add this to the mcpServers object:

{
  "mcpServers": {
    "YouTube Toolbox": {
      "command": "/path/to/bin/uv",
      "args": [
        "--directory",
        "/path/to/py-mcp-youtube-toolbox",
        "run",
        "server.py"
      ],
      "env": {
        "YOUTUBE_API_KEY": "your_youtube_api_key"
      }
    }
  }
}

Cursor IDE

open ~/.cursor/mcp.json

Add this to the mcpServers object:

{
  "mcpServers": {
    "YouTube Toolbox": {
      "command": "/path/to/bin/uv",
      "args": [
        "--directory",
        "/path/to/py-mcp-youtube-toolbox",
        "run",
        "server.py"
      ],
      "env": {
        "YOUTUBE_API_KEY": "your_youtube_api_key"
      }
    }
  }
}

for Docker

{
  "mcpServers": {
    "YouTube Toolbox": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "YOUTUBE_API_KEY=your_youtube_api_key",
        "py-mcp-youtube-toolbox"
      ]
    }
  }
}

Tools Documentation

Video Tools

• search_videos: Search for YouTube videos with advanced filtering options (channel, duration, region, etc.)
• get_video_details: Get detailed information about a specific YouTube video (title, channel, views, likes, etc.)
• get_video_comments: Retrieve comments from a YouTube video with sorting options
• get_related_videos: Find videos related to a specific YouTube video
• get_trending_videos: Get trending videos on YouTube by region

Channel Tools

• get_channel_details: Get detailed information about a YouTube channel (name, subscribers, views, etc.)

Transcript Tools

• get_video_transcript: Extract transcripts/captions from YouTube videos in specified languages
• get_video_enhanced_transcript: Advanced transcript extraction with filtering, search, and multi-video capabilities

Prompt Tools

• transcript_summary: Generate summaries of YouTube video content based on transcripts with customizable options

Resource Tools

• youtube://available-youtube-tools: Get a list of all available YouTube tools
• youtube://video/{video_id}: Get detailed information about a specific video
• youtube://channel/{channel_id}: Get information about a specific channel
• youtube://transcript/{video_id}?language={language}: Get transcript for a specific video

Development

For local testing, you can use the included client script:

# Example: Search videos
uv run client.py search_videos query="MCP" max_results=5

# Example: Get video details
uv run client.py get_video_details video_id=zRgAEIoZEVQ

# Example: Get channel details
uv run client.py get_channel_details channel_id=UCRpOIr-NJpK9S483ge20Pgw

# Example: Get video comments
uv run client.py get_video_comments video_id=zRgAEIoZEVQ max_results=10 order=time

# Example: Get video transcript
uv run client.py get_video_transcript video_id=zRgAEIoZEVQ language=ko

# Example: Get related videos
uv run client.py get_related_videos video_id=zRgAEIoZEVQ max_results=5

# Example: Get trending videos
uv run client.py get_trending_videos region_code=ko max_results=10

# Example: Advanced transcript extraction
uv run client.py get_video_enhanced_transcript video_ids=zRgAEIoZEVQ language=ko format=timestamped include_metadata=true filters.timeRange.start=100 filters.timeRange.end=200 filters.search.query=에이전트 filters.search.caseSensitive=true filters.segment.method=equal filters.segment.count=2

# Example: 

License

MIT License