YouTube MCP

YouTube MCP

A local-first MCP server that lets AI assistants search YouTube, manage your channel and read your analytics, and asks you to approve changes to your channel and content first.

YouTube MCP is a Model Context Protocol server written in TypeScript. It exposes 79 tools to MCP clients such as Claude Code, Claude Desktop, Cursor and Codex. It runs on your own machine over stdio, keeps its OAuth tokens and working data on your disk, and never starts a network listener unless you ask for one.

Anything that changes your YouTube account goes through a preflight, approve, execute flow. The assistant first shows you exactly what it is about to do, and nothing happens until the exact previewed change is approved.

Quick start

1. Get your keys. Follow the beginner setup guide (5 minutes for public research, about 15 with your own channel).
2. Install in your agent. Pick yours in Install in your AI agent.
3. Sign in once (only for your own channel): run the youtube-auth command in Account and creator tools.
4. Ask your agent: "Check my YouTube auth status", then "Search YouTube for talks about MCP".

What it can do

Read (no account needed, just an API key)

• Search videos (with order, date, duration, channel, region and safe-search filters), see what is trending, list the recent uploads of any channel, look up videos and channels.
• List the public comments on a video.
• Fetch a public transcript (best effort; some videos have none).

Read (your own account and channel, via OAuth)

• Your channel, your subscriptions, and comment threads on your channel.
• Creator analytics: channel overview, top videos and audience retention for a date range, plus a flexible report (views by day, traffic sources, devices, countries, demographics and more).
• Your uploaded videos, playlists and playlist items, caption tracks, and the comment moderation queue.

Write (your own account; channel and content changes need preview and approval, viewer actions need `confirm: true`)

• Uploads: resumable video uploads, with status check, resume and cancel. Uploads are private unless you explicitly ask to publish.
• Videos: update title, description and other metadata, and set thumbnails.
• Captions: upload, update, download and delete caption tracks.
• Playlists: create, update, delete, and add, remove or reorder items. New playlists default to private.
• Comments and moderation: reply to comments, set a moderation status (including banning an author), and delete comments on your channel.
• Channel profile: edit your channel description, keywords, country and default language.
• Subscription curation: review subscriptions with subscriber counts and last upload date, then remove many at once after one approval.
• Account actions: subscribe, unsubscribe, rate a video, post a top-level comment (these need a literal confirm: true).

Private viewing analysis (local only)

• Import your Google Takeout YouTube history and get a profile and trend comparison between two date ranges. The data stays in a local SQLite file.
• Save local curation allowlists and generate a finite, proposed queue. The server never applies a queue to your account.

Safety model

Write tools are built so an AI client cannot make a surprise change:

1. Preflight. A youtube_preflight_* tool reads fresh state from YouTube, validates the request and returns an exact preview.
2. Approve. A separate youtube_approve call (one tool for every kind of change), with confirm: true, binds approval to the profile, channel, target, requested change and fresh state. Approvals expire. They are stored locally, so an approved operation survives a server restart until it expires.
3. Execute. The write tool runs only with the same approved inputs and confirm: true.

More guard rails, all from the code:

• Viewer actions (youtube_subscribe, youtube_unsubscribe, youtube_rate_video), youtube_create_comment and the local curation and reset tools are single-step writes: no preflight, but they require a literal confirm: true.
• Mutations are never retried automatically. Ambiguous outcomes are reconciled with a read.
• Public visibility, scheduling, synthetic-media changes and banning an author need an explicit, elevated flag.
• Comment deletion requires the comment to belong to your selected channel.
• Caption downloads never overwrite an existing path or follow symbolic links.
• Creator tools check that the signed-in Google account matches the channel ID you configured.
• The automated tests never make a live mutation.

Full details are in docs/README.md.

Requirements

• Node.js 22.13 or newer
• A Google Cloud project with the YouTube Data API v3 enabled (and the YouTube Analytics API for the creator analytics tools)
• A YouTube Data API key for public reads, and an OAuth desktop client for account and creator tools

Install in your AI agent

No npm publish is needed. Every route below runs the server from the prebuilt tarball attached to the GitHub release with npx -y https://github.com/pratikgh0se/youtube-mcp/releases/download/v0.3.3/youtube-mcp-0.3.3.tgz --transport stdio, except the Claude Desktop bundle, which carries its own copy. You need Node.js 22.13+ on your PATH for the npx routes. Create your Google credentials first with the beginner setup guide (short version: Google credentials). You need at least a YouTube Data API key.

Ready-made files for each client are in configs/. Use the placeholders as shown and never paste a real key into a file you commit.

The first launch downloads the prebuilt release tarball and installs its dependencies, which takes a few seconds on a normal connection. Later launches use npm's cache. To be safe against a client start-up timeout on a slow network, warm the cache once in a terminal first:

npx -y https://github.com/pratikgh0se/youtube-mcp/releases/download/v0.3.3/youtube-mcp-0.3.3.tgz --version

Claude Code

claude plugin marketplace add pratikgh0se/youtube-mcp

claude plugin install youtube-mcp@youtube-mcp

Or inside Claude Code: /plugin marketplace add pratikgh0se/youtube-mcp, then /plugin install youtube-mcp@youtube-mcp. Claude Code asks for your API key (stored in your OS credential store) and four more settings: OAuth client file, profile name and channel ID are required, and the state directory is optional (leave it blank to use ~/.youtube-mcp). The plugin only holds config. The server itself still runs through npx.

Claude Desktop

Download youtube-mcp- .mcpb (one universal bundle for macOS, Windows and Linux) from GitHub Releases and double-click it. Claude Desktop shows an install dialog and asks for your API key. The bundle includes the server, so it needs no npx at run time.

Fallback if you prefer not to use the bundle: add configs/claude-desktop.json to claude_desktop_config.json and restart. The first start downloads the package, which can take a few seconds.

{

"mcpServers": { "youtube-mcp": { "command": "npx", "args": ["-y", "https://github.com/pratikgh0se/youtube-mcp/releases/download/v0.3.3/youtube-mcp-0.3.3.tgz", "--transport", "stdio"], "env": { "YOUTUBE_API_KEY": " " } } } }

Codex CLI

codex mcp add youtube-mcp --env YOUTUBE_API_KEY=<your-youtube-api-key> -- npx -y https://github.com/pratikgh0se/youtube-mcp/releases/download/v0.3.3/youtube-mcp-0.3.3.tgz --transport stdio

That stores the key in ~/.codex/config.toml. To keep it out of the file, use configs/codex.toml instead. It forwards the variables from your shell with env_vars (Codex does not expand ${VAR}) and sets startup_timeout_sec = 180, because the default of 10 seconds is shorter than the first npx run.

[mcp_servers.youtube-mcp]

command = "npx" args = ["-y", "https://github.com/pratikgh0se/youtube-mcp/releases/download/v0.3.3/youtube-mcp-0.3.3.tgz", "--transport", "stdio"] env_vars = ["YOUTUBE_API_KEY"] startup_timeout_sec = 180

Gemini CLI

gemini extensions install https://github.com/pratikgh0se/youtube-mcp

Gemini prompts for your API key (kept in the system keychain, required) and the OAuth client file, profile name and channel ID (needed for your channel's tools; see the setup guide). Change them later with gemini extensions config youtube-mcp. A plain settings.json entry is in configs/gemini-settings.json.

Note: Google stopped serving Gemini CLI to AI Pro, Ultra and free individual users on 2026-06-18. Paid API-key and enterprise users keep it (source). Everyone else should use Antigravity CLI below.

Antigravity CLI

Add this to ~/.gemini/config/mcp_config.json (global) or /.agents/mcp_config.json. It is also in configs/antigravity.json.

{

"mcpServers": { "youtube-mcp": { "command": "npx", "args": ["-y", "https://github.com/pratikgh0se/youtube-mcp/releases/download/v0.3.3/youtube-mcp-0.3.3.tgz", "--transport", "stdio"], "env": { "YOUTUBE_API_KEY": " " } } } }

Cursor

The button reads YOUTUBE_API_KEY from your shell environment. Or add configs/cursor.json to .cursor/mcp.json (