Youtube Streamable MCP Server
No description available
Ask AI about Youtube Streamable MCP Server
Powered by Claude Β· Grounded in docs
I know everything about Youtube Streamable MCP Server. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
YouTube MCP Server
Streamable HTTP MCP server for YouTube β search videos, explore channels, browse playlists, and fetch video details.
Author: overment
[!WARNING] You connect this server to your MCP client at your own responsibility. Language models can make mistakes, misinterpret instructions, or perform unintended actions. Review tool outputs before acting on them. The HTTP layer is designed for convenience during development, not production-grade security.
Notice
This repo works in two ways:
- As a Node/Hono server for local workflows
- As a Cloudflare Worker for remote interactions
How It Works
MCP Client βββΊ YouTube MCP Server βββΊ YouTube Data API v3 βββΊ structured results
All five tools are read-only queries against the YouTube Data API v3. They return both human-readable text summaries and structured JSON output (structuredContent), so LLMs and downstream agents can consume the data directly.
Features
- β Search Videos β Find videos across YouTube by keyword, with sort and date filters
- β Find Channels β Look up channels by name, get channel IDs for further exploration
- β Scan Channels β Fetch the latest videos from any channel
- β Browse Playlists β List playlists from a channel or videos from a specific playlist
- β Video Details β Get full metadata: duration, views, likes, comments, tags, description
- β
Structured Output β Every tool returns both text and
structuredContent(MCP outputSchema) - β Flexible Auth β API key via client header or server config
- β Dual Runtime β Node.js/Bun or Cloudflare Workers
Installation
Prerequisites: Bun and a YouTube Data API v3 key (enable "YouTube Data API v3" in your GCP project).
Ways to Run (Pick One)
- Local (API key) β Fastest start
- Cloudflare Worker (wrangler dev) β Local Worker testing
- Cloudflare Worker (deploy) β Remote production
1. Local (API Key) β Quick Start
git clone <repo>
cd youtube-mcp
bun install
Create .env:
PORT=3000
AUTH_STRATEGY=none
bun dev
# MCP: http://127.0.0.1:3000/mcp
The YouTube API key can be provided in two ways:
Option A β Client header (recommended for multi-user):
Each MCP client request includes the key via X-YouTube-Api-Key header.
Option B β Server-side fallback:
Set API_KEY in .env so the server uses it when no client header is present:
AUTH_STRATEGY=api_key
API_KEY=AIzaSy...your_youtube_key
Connect to your MCP client:
Claude Desktop / Cursor:
{
"mcpServers": {
"youtube": {
"command": "bunx",
"args": [
"mcp-remote",
"http://localhost:3000/mcp",
"--header",
"X-YouTube-Api-Key: ${YOUTUBE_API_KEY}"
]
}
}
}
Or without the header (if API_KEY is set server-side):
{
"mcpServers": {
"youtube": {
"command": "bunx",
"args": ["mcp-remote", "http://localhost:3000/mcp", "--transport", "http-only"],
"env": { "NO_PROXY": "127.0.0.1,localhost" }
}
}
}
2. Cloudflare Worker (Local Dev)
bun x wrangler dev --local | cat
Set the API key as a secret:
bun x wrangler secret put API_KEY
Endpoint: http://127.0.0.1:8787/mcp
3. Cloudflare Worker (Deploy)
- Create KV namespace:
bun x wrangler kv:namespace create TOKENS
-
Update
wrangler.tomlwith the KV namespace ID -
Set secrets:
bun x wrangler secret put API_KEY
- Deploy:
bun x wrangler deploy
Endpoint: https://<worker-name>.<account>.workers.dev/mcp
API Key Resolution
Each tool resolves the YouTube API key in this order:
- Client header
X-YouTube-Api-Keyβ forwarded from the MCP client request - Server config
providerTokenβ falls back toAPI_KEYorBEARER_TOKENfrom env
This lets you run a single server instance for multiple users (each sends their own key) or set a shared key server-side.
Tools
find_channel
Search for YouTube channels by name. Returns channel IDs that can be used with scan_channel.
// Input
{
query: string; // Channel name or search query
maxResults?: number; // 1β10, default 5
}
// Output (structuredContent)
{
query: string;
count: number;
channels: Array<{
channelId: string;
title: string;
description: string;
thumbnailUrl: string;
customUrl?: string;
}>;
}
scan_channel
Get the latest videos from a YouTube channel.
// Input
{
channelId: string; // YouTube channel ID (e.g., UC...)
maxResults?: number; // 1β50, default 10
}
// Output (structuredContent)
{
channelId: string;
videoCount: number;
videos: Array<{
videoId: string;
title: string;
description: string;
publishedAt: string;
thumbnailUrl: string;
}>;
}
search_videos
Search for videos across all of YouTube.
// Input
{
query: string; // Search query
maxResults?: number; // 1β50, default 10
order?: string; // "relevance" | "date" | "viewCount" | "rating" (default: "relevance")
publishedAfter?: string; // ISO 8601 date filter (e.g., "2024-01-01T00:00:00Z")
}
// Output (structuredContent)
{
query: string;
count: number;
videos: Array<{
videoId: string;
title: string;
description: string;
channelId: string;
channelTitle: string;
publishedAt: string;
thumbnailUrl: string;
}>;
}
get_playlist
Dual-mode tool: list playlists from a channel or list videos in a playlist.
// Input (provide one of channelId or playlistId)
{
channelId?: string; // List playlists from this channel
playlistId?: string; // List videos in this playlist
maxResults?: number; // 1β50, default 20
}
// Output when channelId is provided (structuredContent)
{
type: "playlists";
channelId: string;
count: number;
playlists: Array<{
playlistId: string;
title: string;
description: string;
itemCount: number;
thumbnailUrl: string;
}>;
}
// Output when playlistId is provided (structuredContent)
{
type: "videos";
playlistId: string;
count: number;
videos: Array<{
videoId: string;
title: string;
description: string;
channelTitle: string;
position: number;
thumbnailUrl: string;
}>;
}
video_details
Get detailed information about a single video including statistics, duration, and metadata.
// Input
{
videoId: string; // YouTube video ID
}
// Output (structuredContent)
{
videoId: string;
title: string;
description: string;
channelId: string;
channelTitle: string;
publishedAt: string;
duration: string; // ISO 8601 duration (e.g., "PT12M34S")
viewCount: number;
likeCount: number;
commentCount: number;
tags: string[];
thumbnailUrl: string;
}
Examples
1. Discover a channel and list its latest videos
{ "name": "find_channel", "arguments": { "query": "Fireship" } }
Response:
Found 5 channels for "Fireship":
1. Fireship (@Fireship)
ID: UCsBjURrPoezykLs9EqgamOA
...
Then use the channel ID:
{ "name": "scan_channel", "arguments": { "channelId": "UCsBjURrPoezykLs9EqgamOA", "maxResults": 5 } }
2. Search for recent videos on a topic
{
"name": "search_videos",
"arguments": {
"query": "rust programming",
"order": "date",
"maxResults": 10,
"publishedAfter": "2025-01-01T00:00:00Z"
}
}
3. Browse a channel's playlists, then list videos
{ "name": "get_playlist", "arguments": { "channelId": "UCsBjURrPoezykLs9EqgamOA" } }
Then drill into a specific playlist:
{ "name": "get_playlist", "arguments": { "playlistId": "PL0vfts4VzfNjnBhBlI4W3on..." } }
4. Get full details for a video
{ "name": "video_details", "arguments": { "videoId": "dQw4w9WgXcQ" } }
Response:
Title: Rick Astley - Never Gonna Give You Up
Channel: Rick Astley
Published: 2009-10-25T06:57:33Z
Duration: PT3M33S
Views: 1,600,000,000
Likes: 16,000,000
Comments: 2,800,000
Tags: rick astley, never gonna give you up, ...
HTTP Endpoints
| Endpoint | Method | Purpose |
|---|---|---|
/mcp | POST | MCP JSON-RPC 2.0 |
/mcp | GET | SSE stream (Node.js only) |
/health | GET | Health check |
Development
bun dev # Start with hot reload
bun run typecheck # TypeScript check
bun run lint # Lint code (Biome)
bun run build # Production build
bun start # Run production
Architecture
src/
βββ index.ts # Node.js/Bun entry (Hono server)
βββ worker.ts # Cloudflare Workers entry
βββ config/
β βββ env.ts # Re-exports shared config
β βββ metadata.ts # Server & tool descriptions
βββ core/
β βββ capabilities.ts # MCP capabilities (logging, tools)
β βββ context.ts # Request context registry
β βββ mcp.ts # McpServer builder + tool registration
βββ http/
β βββ app.ts # Hono app (CORS, auth, routes)
β βββ auth-app.ts # OAuth Authorization Server (PORT+1)
β βββ middlewares/ # Auth header forwarding (incl. X-YouTube-Api-Key), CORS
β βββ routes/ # /health, /mcp (Streamable HTTP)
βββ shared/
β βββ tools/
β β βββ find-channel.ts # find_channel tool
β β βββ scan-channel.ts # scan_channel tool
β β βββ search-videos.ts # search_videos tool
β β βββ get-playlist.ts # get_playlist tool
β β βββ video-details.ts # video_details tool
β β βββ registry.ts # Tool registry (single source of truth)
β β βββ types.ts # ToolContext, defineTool, ToolResult
β βββ services/
β β βββ http-client.ts # Rate-limited fetch wrapper
β βββ config/
β β βββ env.ts # Unified env parsing (both runtimes)
β βββ storage/ # Token/session stores (file, KV, memory, SQLite)
β βββ oauth/ # OAuth 2.1 PKCE flow + discovery
β βββ mcp/ # JSON-RPC dispatcher (Workers)
β βββ auth/ # Auth strategy types
β βββ crypto/ # AES-GCM encryption for token storage
β βββ http/ # CORS + JSON response helpers
βββ adapters/
β βββ http-hono/ # Hono security middleware, OAuth/discovery routes
β βββ http-workers/ # Workers router, env shim, KV init
βββ utils/ # Logger, cancellation, pagination, etc.
Troubleshooting
| Issue | Solution |
|---|---|
| "YouTube API key required" | Pass the key via X-YouTube-Api-Key header or set API_KEY in .env / wrangler secret put API_KEY |
| "YouTube API error: 403" | The API key may be invalid, or the YouTube Data API v3 isn't enabled in your GCP project |
| "YouTube API error: 429" | Quota exceeded. YouTube allows 10,000 units/day by default. Wait or request a quota increase. |
| "Video not found" | The video ID is wrong, or the video is private/deleted |
| "Either channelId or playlistId must be provided" | get_playlist requires one of the two β pass at least one |
| Workers deploy fails | Ensure KV namespace ID is set in wrangler.toml |
License
MIT
