YouTube MCP Server & CLI

What is the YouTube MCP server & CLI?

The YouTube MCP server & CLI is a free, open source program that lets AI agents read transcripts, research channels and manage your own YouTube channels for you, in 2 ways. The MCP server is what an AI app like Claude, Codex or Cursor connects to, through MCP (Model Context Protocol), the open standard AI apps use to call outside tools.

You ask in plain language. Your AI picks the right tool, and the server makes the call to YouTube, and to Google's API with your own key.

The CLI is the same program as commands. youtube-cli get-transcript --video <url> runs the same code your AI runs when you ask what a video says, whether an agent like Claude Code runs it or you do.

What can you ask it?

Once it's set up, you ask the way you'd ask an assistant. These are real prompts it handles:

Try asking
Summarize this video in five bullets.
Find where she talks about retention in this talk.
Pull the transcripts of these six videos and tell me what the openings have in common.
Which of this channel's last 30 videos actually overperformed?
Read the comments on this video and group them by what people are asking for.
What did my last video do on watch time versus the one before?

The first one shows why this is useful. YouTube's own caption API only serves videos you own, and this reads the public captions of any video, with no key at all.

How to install the YouTube MCP server

Pick your app in the box at the top of this page. Each one is a single command or a pasted block, and transcripts work with nothing else set up.

Set up YouTube

There are 3 levels, and most people never need the third.

Transcripts need nothing. Search, research and comments need an API key, which takes about 10 minutes. Your own channels need OAuth, which takes about half an hour, most of it forms.

The saved channels live in ~/.youtube-mcp-cli/channels.json, encrypted, and every app on this computer uses them. The full walkthrough is in the repo's INSTALL.md.

Check that it works

Run the doctor. It checks yt-dlp, the API key and each connected channel separately.

npx -y @thenavidm/youtube-mcp-cli doctor

Exit code 10 means nothing is configured for that level yet. unauthorized_client means the token came from a different OAuth client than the one set now.

Use the YouTube CLI

The CLI is the same 16 tools as commands. AI agents that run commands, like Claude Code, Codex and OpenCode, use it on their own, and you can type the same commands in a terminal or a script.

Every tool name becomes a command with dashes, so get_transcript runs as youtube-cli get-transcript.

npm install -g @thenavidm/youtube-mcp-cli
youtube-cli
youtube-cli get-transcript --video https://youtu.be/jNQXAC9IVRw
youtube-cli search-videos --query "claude code" --max-results 5
youtube-cli list-my-videos --limit 10

The bare youtube-cli lists every command, and youtube-cli <command> --help shows what a command takes. Deleting a video and replying to a comment ask for --confirm first, like they do for your AI.

These flags work on every command:

A script can branch on the exit code:

MCP server or CLI: which one?

Both are the same program with the same 16 tools. The difference is when your AI pays for them, in the tokens it reads.

An app that loads every tool up front sends the full list with every message, whether you mention YouTube or not. Claude Code doesn't by default: its tool search sends only the tool names and the server's instructions, and loads a tool's full definition when your AI reaches for it.

The CLI costs nothing until YouTube comes up. Then your agent reads its skill file once and runs the commands it needs. With the skill added, Claude Code also lists its one-line description with every message, about 160 tokens.

When the whole conversation is about YouTube, the gap closes. Then the MCP server is the better experience, because you ask in plain language and your AI never has to look up a command.

How to spend less

In Claude Code, leave tool search on, which it is unless you've set ENABLE_TOOL_SEARCH=false.

Turn the server off when you aren't using YouTube, with your AI app's own switch. YOUTUBE_READ_ONLY=1 cuts it to the 13 reading tools.

Or install the CLI and connect the server later, on the days it earns its place. Every tool stays in reach, and the standing cost drops to nothing.

Every number here was measured on September 27, 2026 in Claude Code 2.1.257 with Claude Opus 5. It's the same one-line prompt with and without the server connected, once with tool search off so every tool loads, and once with Claude Code's default. The skill was measured the same way, and other apps and models count tokens a little differently.

What YouTube actually does

A few things on YouTube's side explain most surprises.

Search has its own small allowance

A search draws from its own bucket of 100 calls a day, separate from the 10,000 units the rest of the API shares. It's almost always search that runs out first.

Analytics is only for your own channels

Watch time, retention and traffic sources aren't public for anyone else's channel, at any price, and they lag about 2 days.

Public subscriber counts are rounded

YouTube rounds counts above 1,000 in its public API, so your channel's public count and its own count differ. The one from your own channel is exact.

Shorts skew the averages

Shorts views aren't comparable to long videos on the same channel, so analyze_channel flags them rather than averaging them in.

Every YouTube tool

All 16 tools, grouped the way the repo groups them. 13 only read, and 3 change something on your channel.

Transcripts

Research

Your channels

Is the YouTube MCP server safe?

Writes work from the start, because managing a channel is the point. The two that can't be undone ask first.

delete_video and reply_to_comment ask for a confirm check first, marked Asks first in the tool tables above. YouTube deletes a video at once, with no trash, and a reply is public and notifies someone.

Make it read-only

Set YOUTUBE_READ_ONLY=1 and every write disappears from the tool list, leaving 13. YOUTUBE_ALLOW_DESTRUCTIVE=0 keeps editing titles and blocks the two irreversible tools.

Keep a log of every write

Set YOUTUBE_AUDIT_LOG to a file path. The server writes one line per attempted write, allowed or blocked.

Your data

There's no server of ours in between. Every request goes from your computer to YouTube and Google directly.

youtube-cli login saves your channels and API key to ~/.youtube-mcp-cli/channels.json, encrypted with a key derived from your computer and never stored, so a copied file is useless elsewhere. The audit log is written only when you set YOUTUBE_AUDIT_LOG.

Several channels

Run youtube-cli login once per channel, picking a different one in Google's chooser each time. Brand channels on the same Google account show up there too, and youtube-cli list-accounts shows them all.

Pass --account on the command line, or account through your AI, to pick one. With a single channel connected, you never need it.

YouTube MCP server settings

Every setting is an environment variable in your app's config. None are needed for transcripts, or on a computer where you ran youtube-cli login.

Troubleshooting

Run the doctor first. It names the step that failed and the fix.

If the server doesn't show up in your app at all, run the command your app runs, in a terminal, and read the error.