🔑 Setup

mcp-youtube talks to the YouTube Data API v3 on your behalf, so it needs a one-time OAuth authorisation before its first use.

Run the setup flow

npm run setup

This walks you through:

1. Creating a Google Cloud OAuth client of type Desktop app
2. Opening a browser to authorise the youtube.force-ssl scope
3. Printing the resulting credentials — nothing is written to disk

You then place those values wherever you keep secrets and expose them to the server as environment variables.

Set the OAuth app's publishing status to "In production" in Google Cloud. youtube.force-ssl is a sensitive scope, and while the app is in Testing the refresh token expires after 7 days.

Credential resolution

The server is store-agnostic: it reads three values from the environment and nothing else. Where they come from — a keychain-backed shell export, a secrets manager, or your MCP client's env block — is your choice.

A keychain-backed export keeps the plaintext token out of your shell config:

export MCP_YOUTUBE_REFRESH_TOKEN=$(security find-generic-password -s mcp-youtube-refresh-token -w)

If any of the three are missing from the environment, the server refuses to start and prints:

Missing YouTube OAuth credentials — set MCP_YOUTUBE_CLIENT_ID / MCP_YOUTUBE_CLIENT_SECRET / MCP_YOUTUBE_REFRESH_TOKEN in the environment (run `npm run setup` to mint a refresh token)

Installing the server

The server works with any MCP-compatible client — Claude Desktop, Claude Code, Cursor, Cline, Zed, Continue, and others.

Install the package:

npm install -g @kud/mcp-youtube

In Claude Code or Claude Desktop you can instead install it as a plugin, which wires up the registration for you:

/plugin install youtube@kud

Either way, run npm run setup before first use.

The quota budget

Every design decision in this server — the dry-run default on clean-playlist, the confirm: true guard on destructive tools, the per-tool cost reporting — exists because YouTube's Data API v3 gives every project a fixed 10,000 quota units/day. A single careless search call or bulk delete can burn through a meaningful chunk of that in one shot.