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
- 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:
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 optionsget_related_videos: Find videos related to a specific YouTube videoget_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 languagesget_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 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
Metadata
Release files for iflow-mcp_py-mcp-youtube-toolbox 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_py_mcp_youtube_toolbox-0.1.0.tar.gz | 14.2 kB | Without provenance | Details for iflow_mcp_py_mcp_youtube_toolbox-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_py_mcp_youtube_toolbox-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_py_mcp_youtube_toolbox-0.1.0-py3-none-any.whl |
Total release size: 28.9 kB
Release files / iflow_mcp_py_mcp_youtube_toolbox-0.1.0.tar.gz
| Download URL | iflow_mcp_py_mcp_youtube_toolbox-0.1.0.tar.gz |
|---|---|
| Size | 14.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
37755547beed0229851067a5eb247933a3fd26701cde8f46b8dc1ee09daef0f8
|
|
BLAKE2b-256 checksum How to use checksums |
4de810eb1259b441cb82098ce3aafa3a6a12125989c6c9ebf06a4eb515be39c8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.6.9
|
Release files / iflow_mcp_py_mcp_youtube_toolbox-0.1.0-py3-none-any.whl
| Download URL | iflow_mcp_py_mcp_youtube_toolbox-0.1.0-py3-none-any.whl |
|---|---|
| Size | 14.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
377dd648b15c8e308e802a735fbcdd10bf64b63673caf086d24f81f6184ee02d
|
|
BLAKE2b-256 checksum How to use checksums |
22b898e3545af08156a181bef08cc65b8a1972e3ed57cfb27cdb411b3ef90cd4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.6.9
|
Security for iflow-mcp_py-mcp-youtube-toolbox 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.