YouTube Toolkit
MCP server for YouTube content analysis, transcript extraction, and creator style profiling with intelligent caching and rate limit protection.
This toolkit enables AI assistants to:
- Analyze YouTube channels and their content strategies
- Extract video transcripts without rate limit issues (with intelligent caching)
- Search YouTube and analyze trends in specific niches
- Compare creator styles and teaching approaches
- Identify content gaps and opportunities
- Track channel performance over time
Claude Code Custom Commands
This toolkit includes powerful Claude Code slash commands in the .claude/commands/ directory that automate common YouTube analysis workflows:
- /analyze-channel - Comprehensive channel analysis with metrics, content strategy insights, and growth opportunities
- /research-niche - Research successful content in any YouTube niche to understand what works
- /compare-creators - Compare teaching styles and content approaches between multiple videos
- /track-performance - Track channel performance trends over time with detailed analytics
- /find-content-gaps - Identify underserved topics and content opportunities in your niche
To use these commands in Claude Code:
- Ensure the MCP server is installed and configured (see Quick Start below)
- Type
/in Claude Code to see available commands - Example:
/analyze-channel "UCBJycsmduvYEL83R_U4JriQ"
These commands handle all the complexity of data fetching, analysis, and report generation automatically.
Quick Start for MCP Clients
1. Install the MCP server
# Install using uvx (recommended for stability)
uvx --from youtube-toolkit youtube-toolkit-server
2. Configure your MCP client
For Claude Code
# Add with automatic configuration
claude mcp add youtube-toolkit --uvx youtube-toolkit
# Or with full configuration including API key
claude mcp add-json -s user youtube-toolkit '{"type":"stdio","command":"uvx","args":["--from","youtube-toolkit","youtube-toolkit-server"],"env":{"YOUTUBE_API_KEY":"your-api-key-here","TRANSCRIPT_CACHE_DIR":"~/youtube-transcript-cache","DEFAULT_TRANSCRIPT_DELAY":"10.0","MAX_CACHE_AGE_DAYS":"30"}}'
For Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"youtube-toolkit": {
"command": "uvx",
"args": ["--from", "youtube-toolkit", "youtube-toolkit-server"],
"env": {
"YOUTUBE_API_KEY": "your-youtube-api-key-here",
"TRANSCRIPT_CACHE_DIR": "~/youtube-transcript-cache",
"DEFAULT_TRANSCRIPT_DELAY": "10.0",
"MAX_CACHE_AGE_DAYS": "30"
}
}
}
}
For Cline
Add to .vscode/settings.json in your project:
{
"cline.MCP.mcpServers": {
"youtube-toolkit": {
"command": "uvx",
"args": ["--from", "youtube-toolkit", "youtube-toolkit-server"],
"env": {
"YOUTUBE_API_KEY": "your-youtube-api-key-here",
"TRANSCRIPT_CACHE_DIR": "~/youtube-transcript-cache",
"DEFAULT_TRANSCRIPT_DELAY": "10.0",
"MAX_CACHE_AGE_DAYS": "30"
}
}
}
}
3. Get your credentials (if needed)
- YouTube API Key (optional but recommended): Get from Google Cloud Console
- Create a new project or select existing
- Enable YouTube Data API v3
- Create credentials (API Key)
- Restrict key to YouTube Data API v3 for security
Note: The toolkit works without an API key by using transcript-only features, but channel/video metadata requires the API key.
4. Start using the tools
Once configured, you can ask your AI assistant to:
- "Analyze the YouTube channel UCBJycsmduvYEL83R_U4JriQ"
- "Research what content is succeeding in the Python programming niche"
- "Compare teaching styles between these 3 YouTube videos: [URLs]"
- "Find content gaps in the AI coding tools niche"
- "Track performance trends for channel UCxxxxxx over the last 90 days"
Features
- YouTube channel analysis with comprehensive metrics
- Transcript extraction with intelligent caching and rate limit protection
- Video metadata fetching (views, likes, duration, etc.)
- YouTube search with multiple sort options
- Content gap identification and opportunity analysis
- Support for both stdio and SSE transports
- Comprehensive logging with automatic rotation
- Cross-platform compatibility (Linux, macOS, Windows)
Available Tools
youtube_get_video_transcript
Fetches and caches video transcripts with flexible extraction modes.
Parameters:
video_id(required): YouTube video ID or URLextract_mode(optional, default: 'full'): 'full', 'analysis', 'intro_only', or 'outro_only'use_cache(optional, default: true): Use cached transcript if availabledelay_seconds(optional): Seconds to wait before scraping
Returns:
- Transcript text with timing data and metadata including cache status
youtube_get_video_metadata
Fetches comprehensive metadata for a YouTube video.
Parameters:
video_id(required): YouTube video ID or full URLinclude_statistics(optional, default: true): Include view/like/comment counts
Returns:
- Video title, description, channel info, duration, statistics, and more
youtube_get_channel_videos
Lists recent videos from a YouTube channel with detailed metadata.
Parameters:
channel_id(required): YouTube channel ID (must start with 'UC')max_results(optional, default: 10): Number of videos to return (1-50)include_transcripts(optional, default: false): Fetch transcript for each videouse_cache(optional, default: true): Use cached transcripts when availabledelay_seconds(optional): Seconds between transcript fetches
Returns:
- Channel info with subscriber count, array of videos with metadata
youtube_search_videos
Searches YouTube videos with sorting options.
Parameters:
query(required): Search termsmax_results(optional, default: 10): Number of results (1-50)order(optional, default: 'relevance'): Sort by 'relevance', 'date', 'viewCount', or 'rating'published_after(optional): ISO 8601 date string
Returns:
- Array of video results with metadata
youtube_get_channel_metadata
Fetches comprehensive channel information.
Parameters:
channel_id(required): Channel ID, username, or handle
Returns:
- Channel title, statistics, branding, and configuration
Alternative Configuration Methods
Using a different MCP client
The configuration above works for Claude Desktop, Claude Code, and Cline. For other MCP clients:
- Use
uvx --from youtube-toolkit youtube-toolkit-serveras the command - Set any required environment variables
- Consult your MCP client's documentation for specific configuration format
Running from source (Development only)
For development or testing from source code:
{
"youtube_toolkit": {
"command": "python",
"args": ["-m", "youtube_toolkit.server.app"],
"env": {
"PYTHONPATH": "/path/to/youtube_toolkit"
}
}
}
Troubleshooting
Common Issues
-
"Tool not found" error
- Ensure the server is running and properly configured
- Check that the tool name is spelled correctly (e.g.,
youtube_get_video_transcript) - Verify your MCP client is connected to the server
-
No YouTube API key configured
- The toolkit will still work but only transcript features will be available
- Channel and video metadata tools will return an error
- Add
YOUTUBE_API_KEYto your environment configuration
-
Rate limit errors
- Transcript fetching includes built-in delays to prevent rate limiting
- If you still hit limits, increase
DEFAULT_TRANSCRIPT_DELAY - Cached transcripts are used automatically when available
-
Cache directory issues
- Ensure
TRANSCRIPT_CACHE_DIRexists and is writable - Default is
~/youtube-transcript-cache - Cache files older than
MAX_CACHE_AGE_DAYSare automatically cleaned
- Ensure
Server Connection Issues
If the MCP server fails to connect:
-
Verify uvx is installed:
# Install uv if needed curl -LsSf https://astral.sh/uv/install.sh | sh # macOS/Linux # Or for Windows: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
-
Test the server directly:
# This should output "YouTube Toolkit MCP Server running" uvx --from youtube-toolkit youtube-toolkit-server --version
-
Check your MCP client logs for specific error messages
Requirements
-
Python 3.11 or 3.12
-
Operating Systems: Linux, macOS, Windows
-
YouTube Data API v3 key (optional, for full functionality)
-
Internet access for YouTube API and transcript fetching
-
Write access to cache directory for transcript storage
Logging
The server logs all activity to both stderr and a rotating log file. Log files are stored in OS-specific locations:
- macOS:
~/Library/Logs/mcp-servers/youtube_toolkit.log - Linux:
~/.local/state/mcp-servers/logs/youtube_toolkit.log - Windows:
%LOCALAPPDATA%\mcp-servers\logs\youtube_toolkit.log
Logs rotate at 10MB with 5 backups kept. Control verbosity with LOG_LEVEL:
LOG_LEVEL=DEBUG uvx youtube_toolkit-server
Development
For development setup, testing, and contribution guidelines, see DEVELOPMENT.md.
AI Assistant Configuration
For detailed setup instructions for AI coding assistants (Claude, Cline, etc.), see SETUP_PROMPT.md.
License
This project is licensed under the MIT License. See the LICENSE file for details.
Author
Tim Kitchens - timkitch@codingthefuture.ai
Metadata
Release files for youtube-toolkit 0.2.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 |
|---|---|---|---|---|
| youtube_toolkit-0.2.0.tar.gz | 29.7 kB | Without provenance | Details for youtube_toolkit-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| youtube_toolkit-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for youtube_toolkit-0.2.0-py3-none-any.whl |
Total release size: 53.1 kB
Release files / youtube_toolkit-0.2.0.tar.gz
| Download URL | youtube_toolkit-0.2.0.tar.gz |
|---|---|
| Size | 29.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
129928ba9edce5b49ad3923e234f8a00f82b251ea4eeffddb200b10814caf53f
|
|
BLAKE2b-256 checksum How to use checksums |
0aefe1e5ae3c6b733e0e1da42a80f34dee8f65aac547f4aea2cf5c535b181727
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.11.12
|
Release files / youtube_toolkit-0.2.0-py3-none-any.whl
| Download URL | youtube_toolkit-0.2.0-py3-none-any.whl |
|---|---|
| Size | 23.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
450c6cead15efe11041d57aaebf35c1c00f843318a3104fd1a45805d6772e4dd
|
|
BLAKE2b-256 checksum How to use checksums |
b0a113a83b6144fefba5abbe26ee45e8e3b321542f4b8c6dc4c0a8131c84088d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.11.12
|
Security for youtube-toolkit 0.2.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.