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
- 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:
- Go to "APIs & Services" > "Library"
- Search for and enable "YouTube Data API v3"
- Create credentials:
- Go to "APIs & Services" > "Credentials"
- Click "Create Credentials" > "API key"
- 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:
- Run the MCP Inspector:
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"
]
}
}
}
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 optionsget_related_videos: Find videos related to a specific YouTube videoget_trending_videos: Get trending videos on YouTube by region
get_channel_details: Get detailed information about a YouTube channel (name, subscribers, views, etc.)
get_video_transcript: Extract transcripts/captions from YouTube videos in specified languagesget_video_enhanced_transcript: Advanced transcript extraction with filtering, search, and multi-video capabilities
transcript_summary: Generate summaries of YouTube video content based on transcripts with customizable options
youtube://available-youtube-tools: Get a list of all available YouTube toolsyoutube://video/{video_id}: Get detailed information about a specific videoyoutube://channel/{channel_id}: Get information about a specific channelyoutube://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