YouTube MCP Server

MCP server that brings YouTube to Claude Code — video transcripts, search, metadata, channel info, playlists, comments, trending videos, engagement analytics, chapter extraction, SponsorBlock integration, and most-replayed heatmaps. Uses the YouTube Data API v3, youtube-transcript, and SponsorBlock.

Quick Start

Step 1: Get Your API Key

1. Go to Google Cloud Console
2. Create a project (or select an existing one)
3. Enable the YouTube Data API v3:
   • Go to API Library
   • Click Enable
4. Create an API key:
   • Go to Credentials
   • Click Create Credentials > API key
5. Copy the key (you'll need it in Step 3)

Step 2: Install Prerequisites

• Node.js 18+ - Download here
• Claude Code CLI - Installation guide

Step 3: Install the MCP Server

3.1 Clone the repository

git clone https://github.com/wynandw87/claude-code-youtube-mcp.git
cd claude-code-youtube-mcp

3.2 Install dependencies

macOS / Linux / Windows:

npm install

Note: Dependencies are installed and the server is built automatically in one step.

3.3 Register with Claude Code

Choose your install scope:

Scope	Flag	Who can use it
User (recommended)	-s user	You, in any project
Project	-s project	Anyone who clones this repo
Local	-s local	Only in current directory

Replace YOUR_API_KEY with your actual YouTube Data API key, and use the full path to dist/index.js.

Tip: To get the full path, run this from the cloned directory:

• macOS/Linux: echo "$(pwd)/dist/index.js"
• Windows: echo %cd%\dist\index.js

macOS / Linux:

claude mcp add -s user youtube -e YOUTUBE_API_KEY=YOUR_API_KEY -- node /full/path/to/dist/index.js

Windows (CMD):

claude mcp add -s user youtube -e "YOUTUBE_API_KEY=YOUR_API_KEY" -- node "C:\full\path\to\dist\index.js"

Windows (PowerShell):

claude mcp add -s user youtube -e "YOUTUBE_API_KEY=YOUR_API_KEY" '--' node "C:\full\path\to\dist\index.js"

Alternative: Use the npm helper (if API key is set in environment)

export YOUTUBE_API_KEY=YOUR_API_KEY
npm run install:claude

Step 4: Restart Claude Code

Close and reopen Claude Code for the changes to take effect.

Step 5: Verify Installation

claude mcp list

You should see youtube listed with a Connected status.

---

Features

Transcripts & Captions

• Get Transcript (get_transcript) - Fetch full video transcripts with timestamps, supports multiple languages
• Search Transcript (search_transcript) - Find where a keyword or phrase appears in a video with timestamps
• Clean Transcript (get_clean_transcript) - Transcript with sponsors, intros, outros, and filler removed via SponsorBlock
• Extract Chapters (extract_chapters) - Parse chapter timestamps from video descriptions

Search & Discovery

• Search Videos (search_videos) - Full YouTube search with filters for date, duration, type, and sort order
• Search Within Channel (search_within_channel) - Search for videos from a specific creator
• Get Trending Videos (get_trending_videos) - Currently trending videos by region and category
• Get Channel Videos (get_channel_videos) - Recent uploads from a channel, sorted by date or views

Video & Channel Info

• Video Metadata (get_video_metadata) - Title, description, duration, views, likes, tags, and more
• Channel Info (get_channel_info) - Subscriber count, video count, description, country
• Playlist Items (get_playlist_items) - All videos in a playlist with positions and metadata

Analytics & Engagement

• Calculate Engagement (calculate_engagement) - Like rate, comment rate, and engagement rate from public stats
• Most Replayed (get_most_replayed) - Heatmap data showing which parts viewers rewatch most
• Video Comments (get_video_comments) - Top comments with like counts and reply counts

Utilities

• Parse YouTube URL (parse_youtube_url) - Extract video/channel/playlist IDs from any YouTube URL format

---

Usage

Once installed, use trigger phrases to invoke YouTube tools:

Trigger	Tool	Example
youtube transcript	Get Transcript	"get the youtube transcript for this video"
youtube search	Search Videos	"youtube search for React tutorials"
youtube metadata	Video Metadata	"get youtube metadata for this video"
youtube channel	Channel Info	"get youtube channel info for @ThePrimeagen"
youtube playlist	Playlist Items	"list the videos in this youtube playlist"
youtube comments	Video Comments	"get youtube comments for this video"
youtube trending	Trending Videos	"what's trending on youtube in the US?"
youtube chapters	Extract Chapters	"extract chapters from this youtube video"
youtube engagement	Calculate Engagement	"calculate youtube engagement for this video"
youtube most replayed	Most Replayed	"show the most replayed parts of this youtube video"
youtube clean transcript	Clean Transcript	"get a clean youtube transcript without sponsors"
youtube search transcript	Search Transcript	"search the youtube transcript for 'authentication'"

Or ask naturally:

• "Get the transcript of this YouTube video and summarize it"
• "What are the most replayed parts of this video?"
• "Find recent videos about TypeScript on this channel"
• "How many views and likes does this video have?"
• "Get the comments on this video and summarize the sentiment"
• "Show me the chapters for this tutorial"
• "Get a clean transcript without the sponsor reads"
• "What's trending on YouTube in gaming right now?"

---

Tool Reference

parse_youtube_url

Parse any YouTube URL format and extract identifiers. No API key needed.

Parameters:

• url (string, required) - Any YouTube URL or video ID

Supported formats: youtube.com/watch?v=, youtu.be/, /shorts/, /embed/, /playlist?list=, /channel/, /@handle, /c/, /user/, bare video IDs

get_transcript

Fetch the full transcript/captions of a YouTube video. No API key needed.

Parameters:

• url (string, required) - YouTube video URL or video ID
• lang (string, optional) - Language code for captions (default: "en")

search_transcript

Search within a video's transcript for a keyword or phrase.

Parameters:

• url (string, required) - YouTube video URL or video ID
• query (string, required) - Keyword or phrase to search for
• lang (string, optional) - Language code for captions (default: "en")

extract_chapters

Extract chapter timestamps from a video's description.

Parameters:

• url (string, required) - YouTube video URL or video ID

get_clean_transcript

Fetch transcript with sponsor reads, intros, outros, and filler removed via SponsorBlock.

Parameters:

• url (string, required) - YouTube video URL or video ID
• lang (string, optional) - Language code for captions (default: "en")

get_most_replayed

Get the "most replayed" heatmap data showing which parts viewers rewatch most.

Parameters:

• url (string, required) - YouTube video URL or video ID

Note: Requires approximately 50K+ views to have heatmap data available.

search_videos

Search YouTube with full filter support.

Parameters:

• query (string, required) - Search query
• max_results (number, optional) - Number of results, 1-50 (default: 10)
• order (string, optional) - "relevance", "date", "viewCount", "rating" (default: "relevance")
• duration (string, optional) - "short" (<4min), "medium" (4-20min), "long" (>20min)
• upload_date (string, optional) - "hour", "day", "week", "month", "year"
• type (string, optional) - "video", "channel", "playlist" (default: "video")

get_video_metadata

Get detailed metadata for a YouTube video.

Parameters:

• url (string, required) - YouTube video URL or video ID

Returns: Title, description, channel, duration, view/like/comment counts, tags, category, thumbnails, live status, and more.

get_channel_info

Get YouTube channel information.

Parameters:

• url (string, required) - YouTube channel URL, @handle, or channel ID

Returns: Title, description, subscriber/video/view counts, country, custom URL, and thumbnail.

get_playlist_items

Get all videos in a YouTube playlist.

Parameters:

• url (string, required) - YouTube playlist URL or playlist ID
• max_results (number, optional) - Number of items, 1-50 (default: 25)

get_channel_videos

Get recent videos from a YouTube channel.

Parameters:

• url (string, required) - YouTube channel URL, @handle, or channel ID
• max_results (number, optional) - Number of videos, 1-50 (default: 25)
• order (string, optional) - "date", "viewCount" (default: "date")

get_trending_videos

Get currently trending/popular YouTube videos.

Parameters:

• region_code (string, optional) - ISO 3166-1 alpha-2 country code (default: "US")
• category_id (string, optional) - YouTube category ID (e.g., "10" for Music, "20" for Gaming, "28" for Science & Tech)
• max_results (number, optional) - Number of results, 1-50 (default: 10)

search_within_channel

Search for videos within a specific YouTube channel.

Parameters:

• url (string, required) - YouTube channel URL, @handle, or channel ID
• query (string, required) - Search query
• max_results (number, optional) - Number of results, 1-50 (default: 10)

get_video_comments

Fetch top-level comments from a YouTube video.

Parameters:

• url (string, required) - YouTube video URL or video ID
• max_results (number, optional) - Number of comments, 1-100 (default: 20)
• order (string, optional) - "relevance", "time" (default: "relevance")

calculate_engagement

Calculate engagement metrics for a YouTube video.

Parameters:

• url (string, required) - YouTube video URL or video ID

Returns: View count, like count, comment count, like rate, comment rate, and overall engagement rate.

---

How It Works

This MCP server connects to Claude Code via stdio transport and provides 15 tools:

Tool	Data Source	Needs API Key?
parse_youtube_url	Local parsing	No
get_transcript	youtube-transcript library	No
search_transcript	youtube-transcript library	No
get_clean_transcript	youtube-transcript + SponsorBlock API	No
get_most_replayed	YouTube page (Innertube)	No
extract_chapters	YouTube Data API v3	Yes
search_videos	YouTube Data API v3	Yes
get_video_metadata	YouTube Data API v3	Yes
get_channel_info	YouTube Data API v3	Yes
get_playlist_items	YouTube Data API v3	Yes
get_channel_videos	YouTube Data API v3	Yes
get_trending_videos	YouTube Data API v3	Yes
search_within_channel	YouTube Data API v3	Yes
get_video_comments	YouTube Data API v3	Yes
calculate_engagement	YouTube Data API v3	Yes

Note: 5 tools work without an API key (transcripts, SponsorBlock, heatmaps, URL parsing). The remaining 10 require a YouTube Data API v3 key.

---

Configuration

Environment Variables

Variable	Required	Default	Description
YOUTUBE_API_KEY	Yes	—	YouTube Data API v3 key
YOUTUBE_TIMEOUT	No	30000	API timeout in ms

YouTube API Quota

The YouTube Data API v3 has a daily quota of 10,000 units. Each tool uses a different amount:

Operation	Cost per call
search (search_videos, search_within_channel)	100 units
videos.list (get_video_metadata, get_trending, calculate_engagement)	1 unit
channels.list (get_channel_info, get_channel_videos)	1 unit
playlists.list (get_playlist_items)	1 unit
playlistItems.list (get_playlist_items, get_channel_videos)	1 unit
commentThreads.list (get_video_comments)	1 unit

Tip: Search operations are the most expensive. Use get_channel_videos (1 unit) instead of search_within_channel (100 units) when you just need recent uploads.

---

Troubleshooting

Fix API Key

If you entered the wrong API key, remove and reinstall:

claude mcp remove youtube

Then reinstall using the command from Step 3.3 above (use the same scope you originally installed with).

MCP Server Not Showing Up

Check if the server is installed:

claude mcp list

If not listed, follow Step 3 to install it.

Server Won't Start

1. Verify your API key is valid at Google Cloud Console

2. Check the YouTube Data API is enabled:

   • Go to API Library
   • It should say "Enabled"

3. Check Node.js version (needs 18+):

   node --version
   

4. Ensure the server was built — if dist/index.js is missing, run npm install again

Connection Errors

1. Check that dist/index.js exists — if not, run npm install
2. Verify the path is absolute in your claude mcp add command
3. Restart Claude Code after any configuration changes

Quota Exceeded

If you see "quotaExceeded" errors:

• Wait until midnight Pacific Time (quota resets daily)
• Use a different API key
• Prefer low-cost tools (get_video_metadata at 1 unit) over search tools (100 units)

Transcript Not Available

Some videos have transcripts disabled. The get_transcript tool will return a clear error message. Try:

• A different language code (e.g., lang: "es")
• Auto-generated captions may be available even if manual ones aren't

Timeout Errors

Increase YOUTUBE_TIMEOUT environment variable for slow connections:

claude mcp add -s user youtube -e YOUTUBE_API_KEY=YOUR_KEY -e YOUTUBE_TIMEOUT=60000 -- node /path/to/dist/index.js

View Current Configuration

claude mcp list

---

Contributing

Pull requests welcome! Please keep it simple and beginner-friendly.

License

MIT

---

Made for the Claude Code community