Youtube Streamable

This server is a remote Model Context Protocol (MCP) server for YouTube. It finds videos, channels and playlists, and it reads video metadata. It uses the YouTube Data API v3.

The server runs on Cloudflare Workers and on Bun. It is built on the remote MCP server template, version 2.1, and the official MCP TypeScript SDK 2.3.0. It uses protocol version 2026-07-28. It also accepts clients that use the 2025 protocol versions.

The server URL is the deployed Worker's MCP_PUBLIC_URL, for example https://youtube-mcp.<subdomain>.workers.dev/mcp.

[!WARNING] The production server has no authentication. Anyone who knows the URL can call the tools. Each call uses the quota of the server's YouTube API key. Refer to Authentication.

[!NOTE] Tool results come from YouTube. They can be incomplete or wrong. Examine them before you use them.

Tools

All tools only read data. They do not change anything on YouTube.

Tool	Function	Input
find_channel	Finds channels by name. It gives the channel IDs.	query, maxResults (1–10, default 5)
scan_channel	Gives the latest videos of a channel.	channelId, maxResults (1–50, default 10)
search_videos	Finds videos on all of YouTube.	query, maxResults (1–50, default 10), order (relevance, date, viewCount or rating), publishedAfter (ISO 8601)
get_playlist	Gives the playlists of a channel, or the videos in a playlist.	channelId or playlistId, maxResults (1–50, default 20)
video_details	Gives the details of one video: statistics, duration, tags and description.	videoId

Each tool gives a text summary and structured content. The structured content agrees with the tool's output schema.

The server has no prompts and no resources.

Connect a client

Use the server URL and the Streamable HTTP transport. Clients do not send a token or an API key.

Client	Procedure
Claude Code	Run claude mcp add --transport http youtube <server URL>.
MCP Inspector	Run bun run inspector. Select Streamable HTTP. Enter the server URL.
VS Code	Add { "servers": { "youtube": { "type": "http", "url": "<server URL>" } } } to .vscode/mcp.json.

Browser clients must use an origin in MCP_ALLOWED_ORIGIN_HOSTNAMES. In production, these are claude.ai, claude.com and the hosts of the operator's own browser clients.

Configuration

The server identity (name, version and instructions) is in src/server.ts. The production values of all variables are in wrangler.production.jsonc, which is gitignored; wrangler.production.example.jsonc shows its shape.

The server has two settings of its own. They are in src/settings.ts:

Variable	Default	Function
API_KEY		Required. The YouTube Data API v3 key. The server sends it to YouTube only, as the key query parameter. Store it as a secret.
PROVIDER_API_URL	https://www.googleapis.com/youtube/v3	The YouTube API address. Change it only to send tests to a local mock.

The other variables belong to the template: MCP_PUBLIC_URL, MCP_ALLOWED_HOSTS, MCP_ALLOWED_ORIGIN_HOSTNAMES, MCP_LEGACY_MODE, MCP_MAX_REQUEST_BYTES, AUTH_MODE, LOG_LEVEL, NODE_ENV, HOST and PORT. The file .env.example describes all of them. The template README gives their defaults.

If a setting is not valid, the server shows all problems at the same time. Bun does not start. A Worker records the problems in the log and sends a 500 response to all requests.

Authentication

In production, AUTH_MODE is none. The server accepts all requests that pass the Host and Origin checks. It does not use the caller's identity. It calls YouTube with its own key (API_KEY).

The risk: anyone who finds the URL can use the YouTube API quota of the key. When the quota is used, all tools give the error YouTube API error: 403 until the quota resets.

To restrict access, use one of the template's other modes:

• AUTH_MODE=bearer: all clients send one shared token, BEARER_TOKEN. Each client must then send the header Authorization: Bearer <token>.
• AUTH_MODE=oauth: an external authorization server signs users in.

For the procedures, refer to docs/auth.md in the template. Before you change the mode, make sure that every client (Alice, Wonderlands, Claude.ai) can send the credentials.

Deployment

Refer to docs/deploy.md. It gives the Worker, the secret, the Durable Object migrations and the steps to deploy.

Development

Requirements: Bun 1.4 or later, and Node.js 22.18 or later.

1. Install the dependencies:

   bun install
   

2. Copy .env.example to .env. Set API_KEY to a YouTube Data API v3 key.

3. Start the server:

   bun run dev
   

The server URL is http://127.0.0.1:3000/mcp.

To use the Cloudflare local runtime, put API_KEY=… in .dev.vars, then run bun run dev:worker. The server URL is then http://127.0.0.1:8787/mcp.

Script	Function
bun run check	Does the type check, the lint check and the tests. It also checks the generated Worker types.
bun run test:smoke	Starts the real server on Bun and on workerd. YouTube is replaced by a local mock.
bun run deploy	Deploys with wrangler.production.jsonc.
bun run types:worker	Makes the Worker types again. Run it after you change wrangler.jsonc.

The project structure is the template's:

src/
  server.ts      Server identity, instructions and dependencies
  settings.ts    API_KEY and PROVIDER_API_URL
  tools/         One file for each tool. index.ts lists them.
  services/      youtube.ts: the YouTube Data API client
  platform/      Template code. Do not change it.
  bun.ts         Entry point for Bun
  worker.ts      Entry point for Cloudflare Workers
tests/           Tests for each tool, the service, the platform, and the contract with the earlier server
scripts/         Smoke tests and the local YouTube mock

tests/contract.test.ts and tests/routes.test.ts compare the server with the deployed server before the template 2.1 migration. The recorded data is in tests/fixtures/. A change to a tool name, an input schema, an output schema or a route makes these tests fail.

License

MIT