youtube-kit

youtube-kit

[CI] [PyPI] [Python] [License: MIT] [Listed on mcpservers.org]

YouTube CLI (ytk) and MCP server, built for agents and humans. Let Claude Code, Codex, Cursor, Claude Desktop or ChatGPT work on your channel: analytics, transcripts, uploads, metadata, playlists and comment moderation. It handles several channels, and you can run the same commands in your own terminal.

[Claude Code answering "what were my top 3 videos in the last 28 days?" with ytk]

Quick start

uv tool install youtube-kitytk auth login      # one-time Google Cloud setup, then pick your channel

You need a Google account with a YouTube channel, and uv (brew install uv on macOS). The first ytk auth login takes about 5 minutes: it opens each Google Cloud page, says what to click and picks up the file you download.

ytk analytics --by video --since 90d --limit 5     # your top videos of the last 90 daysytk comment list --status held                     # comments waiting for reviewytk caption transcript VIDEO | jq -r .text         # what you say in one of your videosytk channel get @mkbhd | jq .stats                 # any public channel

[ytk commands piping JSON into jq]

Or ask your agent: "Which of my videos got the most views this month, and are any comments waiting for review?"

Use it from your agent

Skill: Claude Code, Codex, Cursor and other shell agents

A short skill teaches the agent the CLI. It loads only when a YouTube task comes up.

claude plugin install youtube-kit --marketplace eukosh/youtube-kit   # Claude Codecodex plugin marketplace add eukosh/youtube-kit                      # Codex, then:codex plugin add youtube-kit@youtube-kitnpx skills add eukosh/youtube-kit -g                                 # Cursor and others

The plugins follow ytk releases. Codex updates them at startup; Claude Code does once you turn on auto-update under /plugin → Marketplaces. With npx skills, run npx skills update.

MCP: Claude Desktop, ChatGPT and other MCP clients

ytk mcp serves the same operations as tools. In Claude Code:

claude mcp add youtube -- uvx youtube-kit mcp

In clients configured with JSON (Claude Desktop, Cursor and others):

{  "mcpServers": {    "youtube": { "command": "uvx", "args": ["youtube-kit", "mcp"] }  }}

In the ChatGPT desktop app: Settings → MCP servers → Add server → STDIO, with the command uvx youtube-kit mcp. Codex shares that setting (codex mcp add youtube -- uvx youtube-kit mcp).

The server uses your ytk auth login logins. If you also installed ytk with uv tool install, uvx runs that installed version: ytk upgrade updates both. Restart the MCP client afterwards. Not set up yet? The model can walk you through it with the setup_guide tool.

What it covers

Not covered: localizations, live streaming and channel memberships. ytk --help lists every command, and the skill fits them on one page with jq recipes.

Channels and login

ytk auth login connects one channel. Run it again for each of your other channels, including brand channels: pick the one you want when Google asks.

ytk channel mine                                           # your channels; one is the defaultytk auth switch @second                                    # change the defaultytk video upload clip.mp4 --title Hi --my-channel @third   # use another channel for one commandytk auth logout @third

Commands work on the default channel unless --my-channel names another, by UC… ID, @handle or exact title. MCP tools take my_channel the same way, so you can say "upload this to my gaming channel". YOUTUBE_CHANNEL sets the default for one shell or one MCP server.

Why your own Google Cloud client. YouTube's daily quota of 10,000 units belongs to a Cloud project. A client shipped inside ytk would split one quota among all its users. Yours is shared by your channels only.

Let an agent set it up. ytk auth guide (setup_guide over MCP) lists what's left, with links and the values to enter. With the gcloud CLI signed in, the agent can create the project and enable the APIs for you. The rest needs your browser. Already have the client JSON? Run ytk auth login --client-secrets FILE.

[The guided ytk auth login setup]

Built for agents

• JSON out, exit codes for failures. Every command prints one JSON document on stdout. On failure, stdout stays empty, the last line of stderr is {"error": {"type": "not_found", "message": "..."}}, and the exit code names the type: 2 bad input, 3 not found, 4 not authorized, 5 quota exceeded, 6 forbidden, 7 network, 8 confirmation required, 9 protected, 10 timeout, 1 anything else. The skill tells agents what to do about each. At a terminal you get colored JSON and plain-sentence errors.
• Forgiving inputs. Pass IDs or pasted YouTube URLs, @handles for channels, and dates or spans like 90d.
• Quota costs up front. Each command's --help and each MCP tool description states what it spends.
• One core. The CLI and the MCP server are thin layers over the same code, and a test fails if either misses an operation.
• Guarded deletes. See below.
• Update notices. ytk checks PyPI once a day in the background and tells you when a newer release is out: after the output at a terminal, as an {"update": ...} stderr line for agents, and in the MCP server's instructions at startup. ytk upgrade installs it. Turn the check off with check = false under [updates] in config.toml or YTK_NO_UPDATE_CHECK=1; it's also off when CI or NO_UPDATE_NOTIFIER is set.

Deleting

YouTube has no trash, and agents make mistakes. So deleting videos, playlists, comments and caption tracks is guarded:

• Two steps. The first call deletes nothing. At a terminal you get a [y/N] prompt. An agent gets exit 8 with a description of the target and must run the command again with --confirm <id>, so the approval always names the exact thing being deleted.

• Damage limit. A video with more than 100 views, or one that is public and was uploaded more than 7 days ago, can't be deleted here at all (exit 9). Delete those in YouTube Studio. The limits live in config.toml (ytk auth status shows where):

  toml

  [delete_protection]max_views = 100max_public_age_days = 7

• Harness approval. Have your agent ask you before every delete. In Claude Code, add this to .claude/settings.json:

  json

  {"permissions": {"ask": ["Bash(ytk video delete:*)", "Bash(ytk playlist delete:*)", "Bash(ytk comment delete:*)", "Bash(ytk caption delete:*)"]}}

• Idempotent. Deleting something that is already gone succeeds with "already_gone": true.

This stops mistakes, not a determined agent. Anything holding your OAuth token can call the API directly.

Quota

Google gives each Cloud project 10,000 units a day, resetting at midnight Pacific time. Reads cost 1 unit per request, most writes 50, and guarded deletes 52, or 102 for a caption track (they look up the target and check ownership first). search and uploads don't use those units: each gets its own 100 calls a day, one per page of 50 search results or per upload. ytk analytics and ytk impressions use the separate YouTube Analytics and Reporting API quotas.

Contributing

See CONTRIBUTING.md for the development setup and CHANGELOG.md for what changed. Report security issues privately, as SECURITY.md describes.

License

MIT. youtube-kit is not affiliated with or endorsed by Google or YouTube. YouTube is a trademark of Google LLC.