# YouTube MCP Server

A Model Context Protocol (MCP) server for YouTube, running on **Cloudflare Workers** using the Agents SDK (`McpAgent`). Enables AI language models to interact with YouTube content through 18 MCP tools.

## Deployment

```bash
# Install dependencies
npm install

# Set secrets
npx wrangler secret put YOUTUBE_API_KEY
npx wrangler secret put GOOGLE_OAUTH_CLIENT_ID    # Required for transcripts
npx wrangler secret put GOOGLE_OAUTH_CLIENT_SECRET # Required for transcripts

# Deploy
npx wrangler deploy

# MCP endpoint: https://youtube-mcp-server.<your-subdomain>.workers.dev/mcp
```

## Development

```bash
# Local dev with auto-reload
npm run dev

# Typecheck
npm run typecheck
```

Create a `.env` file for local development (see `.env.example`), then:
```bash
npx wrangler dev --port 8787
```

## Available Tools (18)

### Video
| Tool | Description |
|------|-------------|
| `videos_getVideo` | Get detailed video information |
| `videos_searchVideos` | Search videos with channel-level filtering |
| `videos_getVideoStats` | Get view count, likes, comments statistics |
| `videos_getTrendingVideos` | Get trending videos by region |
| `videos_getRelatedVideos` | Find related videos ("Up Next" suggestions) |

### Transcript
| Tool | Description |
|------|-------------|
| `transcripts_getTranscript` | Retrieve video captions (requires Google OAuth) |
| `transcripts_searchTranscript` | Search within a video transcript |
| `transcripts_getTimestampedTranscript` | Get transcript with human-readable timestamps |

### Channel
| Tool | Description |
|------|-------------|
| `channels_getChannel` | Get channel information with enrichment |
| `channels_getChannels` | Bulk channel lookup |
| `channels_searchChannels` | Search channels with subscriber/creator filtering |
| `channels_findCreators` | Discover creators matching a topic |
| `channels_listVideos` | List recent videos from a channel |
| `channels_getStatistics` | Get channel subscriber/video/view counts |
| `channels_getPlaylists` | Get all playlists by a channel |

### Playlist
| Tool | Description |
|------|-------------|
| `playlists_getPlaylist` | Get playlist details |
| `playlists_getPlaylistItems` | List videos in a playlist |
| `playlists_searchPlaylists` | Search for public playlists |

## Authentication

- **15 tools** (video, channel, playlist) use only the YouTube Data API key
- **3 transcript tools** require Google OAuth 2.0 (YouTube Captions API requires it)

To enable transcripts:
1. Create OAuth 2.0 credentials in [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
2. Add redirect URI: `https://your-worker.workers.dev/auth/google/callback`
3. Set secrets and deploy
4. Visit `/auth/google` on your worker to authorize

## Architecture

Built on [Cloudflare Workers](https://workers.cloudflare.com/) using:
- `agents` (McpAgent) — Durable Object-backed MCP server
- `@modelcontextprotocol/sdk` — MCP protocol implementation
- `zod` — Input validation for all tool schemas
- KV — Response caching (1h search, 24h details)

No `googleapis`, `youtube-transcript`, or `ytdl-core` — all YouTube API calls use native `fetch()`.