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

Prerequisites
Installation
Configure MCP Settings
Tools Documentation
Development
License

Prerequisites

Python: Install Python 3.12 or higher
YouTube API Key:
- Go to Google Cloud Console
- Create a new project or select an existing one
- Enable the YouTube Data API v3:
  1. Go to "APIs & Services" > "Library"
  2. Search for and enable "YouTube Data API v3"
- 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

Install UV package manager:

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

Create and activate virtual environment:

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

Install dependencies:

uv pip install -r requirements.txt

Environment variables:

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

Using Docker

Build the Docker image:

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

Run the container:

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

Using Local

Run the server:

mcp run server.py

Run the MCP Inspector:

mcp dev server.py

Configure MCP Settings

Add the server configuration to your MCP settings file:

Claude desktop app

To install automatically via Smithery:

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

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 start_time=100 end_time=200 query=에이전트 case_sensitive=true segment_method=equal segment_count=2

# Example:

License

MIT License

YouTube Toolbox

README Documentation