YouTube MCP Server

A Model Context Protocol (MCP) server providing full YouTube Data API v3 search and retrieval capabilities for AI agents.

Installation

npm install @htekdev/youtube-mcp-server

Or run directly with npx:

npx @htekdev/youtube-mcp-server

Configuration

For Claude Desktop

Add to your claude_desktop_config.json:

{
  "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

1. Go to Google Cloud Console
2. Create a new project or select existing
3. Enable the YouTube Data API v3
4. 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 |

License

MIT

Author

htekdev