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:
npm install -
Create a
.envfile in the root directory:YOUTUBE_API_KEY=your_youtube_api_key_here PORT=3000
Usage
Building and Running
-
Build the project:
npm run build -
Run the server (HTTP transport):
npm startThe server will listen on port 3000 (or PORT environment variable) and accept MCP requests at
/mcpendpoint. -
Run in development mode:
npm run dev -
Clean build artifacts:
npm run clean
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
/mcpendpoint - 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)
- Optional query parameter:
Tools
Basic Tools
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
Statistical Tools
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
Discovery Tools
get-trending-videos- Retrieve trending videos by region and categoryget-video-categories- Get available video categories for a specific region
Analysis Tools
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
Using the Statistical Tools
// 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"
}
}
Using the Enhanced Transcript Tool
// 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