{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["@htekdev/youtube-mcp-server"],
      "env": {
        "YOUTUBE_API_KEY": "your_api_key_here"
      }
    }
  }
}

For Other MCP Clients

Run the server directly:

YOUTUBE_API_KEY=your_api_key npx @htekdev/youtube-mcp-server

Getting an API Key

Go to Google Cloud Console
Create a new project or select existing
Enable the YouTube Data API v3
Create an API key credential

You can also configure the API key at runtime using the setup_youtube tool.

Available Tools

Setup & Status

Tool	Description
`setup_youtube`	Configure API key and defaults
`youtube_status`	Check configuration status

Search

Tool	Description
`youtube_search`	Full-featured search with all filters
`youtube_search_videos`	Simplified video search
`youtube_search_related`	Find videos related to a specific video

Videos

Tool	Description
`youtube_video_details`	Get comprehensive video information
`youtube_video_list`	Batch retrieve multiple videos
`youtube_trending`	Get trending/popular videos

Channels

Tool	Description
`youtube_channel_details`	Get channel info (by ID, handle, or username)
`youtube_channel_videos`	List videos from a channel
`youtube_channel_search`	Search within a specific channel

Playlists

Tool	Description
`youtube_playlist_details`	Get playlist information
`youtube_playlist_items`	List all videos in a playlist
`youtube_playlists_by_channel`	Get all playlists from a channel

Comments

Tool	Description
`youtube_comment_threads`	Get top-level comments on a video
`youtube_comment_replies`	Get replies to a specific comment

Other

Tool	Description
`youtube_captions_list`	List available captions/subtitles
`youtube_live_broadcasts`	Search for live streams

Usage Examples

Search for Videos

{
  "tool": "youtube_search",
  "args": {
    "q": "machine learning tutorial",
    "type": "video",
    "maxResults": 10,
    "order": "viewCount",
    "videoDuration": "medium"
  }
}

Get Video Details

{
  "tool": "youtube_video_details",
  "args": {
    "videoId": "dQw4w9WgXcQ",
    "parts": ["snippet", "statistics", "contentDetails"]
  }
}

Get Channel by Handle

{
  "tool": "youtube_channel_details",
  "args": {
    "handle": "@MrBeast"
  }
}

Search Live Streams

{
  "tool": "youtube_live_broadcasts",
  "args": {
    "q": "gaming",
    "eventType": "live",
    "maxResults": 10
  }
}

Development

Prerequisites

Node.js >= 18.0.0
npm

Setup

npm install

Running Tests

npm test              # Run tests once
npm run test:watch    # Watch mode
npm run test:coverage # With coverage report

Type Checking

npm run typecheck

Building

npm run bundle

API Quota Notes

YouTube Data API has quota limits (default 10,000 units/day). Tool quota costs:

Operation	Cost
Search	100 units
Videos list	1 unit
Channels list	1 unit
Playlists list	1 unit
PlaylistItems list	1 unit
CommentThreads list	1 unit
Comments list	1 unit
Captions list	50 units