YouTube MCP Server
A Model Context Protocol (MCP) server for interacting with YouTube data. This server provides resources and tools to query YouTube videos, channels, comments, and transcripts through a stdio interface.
Features
- Search for YouTube videos with advanced filtering options
- Get detailed information about specific videos and channels
- Compare statistics across multiple videos
- Discover trending videos by region and category
- Analyze channel performance and video statistics
- Retrieve video comments and transcripts/captions
- Generate video analysis and transcript summaries
Prerequisites
- Node.js (v16+)
- YouTube Data API key
Installation
Installing via Smithery
To install YouTube MCP Server for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install @coyaSONG/youtube-mcp-server --client claude
Installing Manually
- Clone this repository:
git clone https://github.com/coyaSONG/youtube-mcp-server.git
cd youtube-mcp-server
- Install dependencies:
- Create a
.env file in the root directory:YOUTUBE_API_KEY=your_youtube_api_key_here
PORT=3000
Usage
Building and Running
- Build the project:
- Run the server (HTTP transport):The server will listen on port 3000 (or PORT environment variable) and accept MCP requests at
/mcp endpoint. - Run in development mode:
- Clean build artifacts:
HTTP Transport Migration
Migration Status: ✅ Complete - Successfully migrated from STDIO to Streamable HTTP transport
This server has been updated to use the modern Streamable HTTP transport as required by Smithery hosting platform. The migration includes:
- Modern Protocol: Uses Streamable HTTP transport (protocol version 2025-03-26)
- Express.js Framework: Built on Express.js for robust HTTP handling
- Session Management: Supports stateful operations with proper session tracking
- MCP Endpoint: All requests handled at
/mcp endpoint - Backwards Compatibility: Maintains full compatibility with all existing tools and resources
- Enhanced Performance: Improved scalability and better error handling
Testing the Migration
Local Testing:
# Start the server
npm start
# Test with MCP Inspector
npx @modelcontextprotocol/inspector
# Connect to: http://localhost:3000/mcp
Smithery Integration:
- The server is fully compatible with Smithery's new hosting requirements
- All existing Claude Desktop integrations will continue to work seamlessly
- No changes required for end users
Docker Deployment
The project includes a Dockerfile for containerized deployment:
# Build the Docker image
docker build -t youtube-mcp-server .
# Run the container with HTTP transport
docker run -p 3000:3000 --env-file .env youtube-mcp-server
Important: The container now exposes port 3000 for HTTP-based MCP communication instead of STDIO.
API Reference
Resources
youtube://video/{videoId} - Get detailed information about a specific videoyoutube://channel/{channelId} - Get information about a specific channelyoutube://transcript/{videoId} - Get transcript for a specific video- Optional query parameter:
?language=LANGUAGE_CODE (e.g., en, ko, ja)
search-videos - Search for YouTube videos with advanced filtering optionsget-video-comments - Get comments for a specific videoget-video-transcript - Get transcript for a specific video with optional languageenhanced-transcript - Advanced transcript extraction with filtering, search, and multi-video capabilitiesget-key-moments - Extract key moments with timestamps from a video transcript for easier navigationget-segmented-transcript - Divide a video transcript into segments for easier analysis
get-video-stats - Get statistical information for a specific videoget-channel-stats - Get subscriber count, view count, and other channel statisticscompare-videos - Compare statistics across multiple videos
get-trending-videos - Retrieve trending videos by region and categoryget-video-categories - Get available video categories for a specific region
analyze-channel-videos - Analyze performance trends of videos from a specific channel
Prompts
video-analysis - Generate an analysis of a YouTube videotranscript-summary - Generate a summary of a video based on its transcript with customizable length and keywords extractionsegment-by-segment-analysis - Provide detailed breakdown of content by analyzing each segment of the video
Examples
Accessing a Video Transcript
youtube://transcript/dQw4w9WgXcQ
Getting a Transcript in a Specific Language
youtube://transcript/dQw4w9WgXcQ?language=en
// Get video statistics
{
"type": "tool",
"name": "get-video-stats",
"parameters": {
"videoId": "dQw4w9WgXcQ"
}
}
// Compare multiple videos
{
"type": "tool",
"name": "compare-videos",
"parameters": {
"videoIds": ["dQw4w9WgXcQ", "9bZkp7q19f0"]
}
}
Using the Transcript Summary Prompt
{
"type": "prompt",
"name": "transcript-summary",
"parameters": {
"videoId": "dQw4w9WgXcQ",
"language": "en"
}
}
// Basic multi-video transcript extraction
{
"type": "tool",
"name": "enhanced-transcript",
"parameters": {
"videoIds": ["dQw4w9WgXcQ", "9bZkp7q19f0"],
"format": "timestamped"
}
}
// With search and time filtering
{
"type": "tool",
"name": "enhanced-transcript",
"parameters": {
"videoIds": ["dQw4w9WgXcQ"],
"filters": {
"timeRange": {
"start": 60, // Start at 60 seconds
"end": 180 // End at 180 seconds
},
"search": {
"query": "never gonna",
"contextLines": 2
}
},
"format": "merged"
}
}
// With smart segmentation for easier analysis
{
"type": "tool",
"name": "enhanced-transcript",
"parameters": {
"videoIds": ["dQw4w9WgXcQ"],
"filters": {
"segment": {
"count": 5,
"method": "smart" // Breaks at natural pauses
}
},
"format": "timestamped",
"language": "en"
}
}
Using the Enhanced Transcript Analysis Features
// Get key moments from a video
{
"type": "tool",
"name": "get-key-moments",
"parameters": {
"videoId": "dQw4w9WgXcQ",
"maxMoments": "5"
}
}
// Get a segmented transcript
{
"type": "tool",
"name": "get-segmented-transcript",
"parameters": {
"videoId": "dQw4w9WgXcQ",
"segmentCount": "4"
}
}
// Get a segment-by-segment analysis
{
"type": "prompt",
"name": "segment-by-segment-analysis",
"parameters": {
"videoId": "dQw4w9WgXcQ",
"segmentCount": "4"
}
}
// Get customized transcript summary
{
"type": "prompt",
"name": "transcript-summary",
"parameters": {
"videoId": "dQw4w9WgXcQ",
"language": "en",
"summaryLength": "detailed",
"includeKeywords": "true"
}
}
Error Handling
The server handles various error conditions, including:
- Invalid API key
- Video or channel not found
- Transcript not available
- Network issues
License
MIT
Acknowledgements