youtube-kit

youtube-kit

エージェントと人間のために作られた、YouTube CLI（ytk）および MCP サーバーです。Claude Code、Codex、Cursor、Claude Desktop、ChatGPT を使って、チャンネルの分析、文字起こし、アップロード、メタデータ、プレイリスト、コメントのモデレーションを行えます。複数のチャンネルに対応しており、同じコマンドを自分のターミナルでも実行できます。

クイックスタート

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

YouTube チャンネルを持つ Google アカウントと、uv（macOS では brew install uv）が必要です。最初の ytk auth login には約 5 分かかります。Google Cloud の各ページを開いて、クリックする場所を案内し、ダウンロードしたファイルを自動で見つけます。

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

または、エージェントに尋ねてみましょう。「今月、最も再生された動画はどれですか？確認待ちのコメントはありますか？」

エージェントから使う

スキル：Claude Code、Codex、Cursor、その他のシェルエージェント

短いスキルで CLI の使い方をエージェントに教えます。YouTube に関するタスクが発生したときだけ読み込まれます。

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

プラグインは ytk のリリースに追従します。Codex は起動時に更新します。Claude Code は /plugin → Marketplaces で自動更新を有効にすると更新します。npx skills の場合は、npx skills update を実行してください。

MCP：Claude Desktop、ChatGPT、その他の MCP クライアント

ytk mcp は同じ操作をツールとして提供します。Claude Code では：

claude mcp add youtube -- uvx youtube-kit mcp

JSON で設定するクライアント（Claude Desktop、Cursor など）では：

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

ChatGPT デスクトップアプリでは、Settings → MCP servers → Add server → STDIO に進み、コマンド uvx youtube-kit mcp を入力します。Codex もこの設定を共有します（codex mcp add youtube -- uvx youtube-kit mcp）。

サーバーは ytk auth login でのログイン情報を使用します。uv tool install でも ytk をインストールした場合、uvx はそのインストール済みバージョンを実行します。ytk upgrade で両方を更新できます。その後、MCP クライアントを再起動してください。まだ設定していませんか？モデルが setup_guide ツールを使って設定を案内できます。

対応範囲

分野	操作
アナリティクス	合計、または日別、月別、動画別、国別、デバイス別、OS 別、トラフィックソース別、およびその詳細（検索語句、関連動画、サイト）、再生場所、年齢、性別、登録状況、コンテンツの種類（長尺動画、Shorts、ライブ配信）、共有サービス別の内訳；動画の視聴者維持率；動画、コンテンツの種類、国、トラフィックソースによる絞り込み
インプレッション	サムネイルのインプレッション数とクリック率。合計、日別、動画別
動画	取得、カテゴリ、アップロード（再開可能、進捗表示付き）、メタデータの更新、サムネイルの設定、処理の完了待ち、高評価または低評価、評価の確認、削除
字幕	自分の動画の字幕。自分で追加した字幕または YouTube の自動生成字幕を取得し、必要に応じて機械翻訳；任意の動画の字幕トラックの一覧表示；アップロード、差し替え、非表示、削除
コメント	一覧表示（公開済み、審査待ち、スパムの可能性あり）、返信の一覧表示、投稿、返信、編集、削除、承認、保留、却下、投稿者のブロック
再生リスト	一覧表示、取得、アイテムの表示、作成、更新、画像の設定、追加、削除、移動、削除
チャンネル	取得、最近のアクティビティ、ログイン中の自分のチャンネル、概要情報（説明、キーワード、国、言語、予告編）、バナー、透かし、ホームページのセクション
検索	動画、チャンネル、再生リスト。チャンネルまたは日付で絞り込み
チャンネル登録	一覧表示、登録、登録解除

対象外：ローカライズ、ライブ配信、チャンネルメンバーシップ。ytk --help にすべてのコマンドが記載されており、スキルには、jq のレシピとともに1ページにまとめられています。

チャンネルとログイン

ytk auth login は1つのチャンネルに接続します。他のチャンネル（ブランドチャンネルも含む）についても、Googleから選択を求められたときに接続したいチャンネルを選んで、コマンドを再度実行してください。

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

コマンドは、--my-channel に別のチャンネルを指定しない限り、デフォルトのチャンネルで動作します。指定には、UC… ID、@handle、または正確なタイトルを使います。MCP ツールでも同じように my_channel を指定できるため、「これをゲームチャンネルにアップロードして」と指示できます。YOUTUBE_CHANNEL を設定すると、1つのシェルまたは1つの MCP サーバーのデフォルトチャンネルを指定できます。

独自の Google Cloud クライアントを使う理由。 YouTube の1日あたりの割り当て10,000ユニットは、Cloud プロジェクトに紐付けられています。ytk に同梱されたクライアントでは、すべてのユーザーで1つの割り当てを分け合うことになります。独自のクライアントなら、自分のチャンネル間でのみ共有されます。

エージェントにセットアップを任せる。 ytk auth guide（MCP では setup_guide）を実行すると、残りの作業と入力する値へのリンクが表示されます。gcloud CLI にサインイン済みであれば、エージェントがプロジェクトを作成し、API を有効にできます。それ以外の作業にはブラウザーが必要です。クライアント JSON をすでにお持ちの場合は、ytk auth login --client-secrets FILE を実行してください。

手動セットアップ、ファイル、環境変数

ガイド付きセットアップでは、次の作業を行います。

1. Google Cloud Console でプロジェクトを作成し、YouTube Data API v3、YouTube Analytics API、YouTube Reporting API（インプレッション数とクリック率用）を有効にします。
2. Google Auth Platform で Get started をクリックし、対象ユーザーを External にします。Branding でホームページ（https://github.com/eukosh/youtube-kit）、プライバシーポリシーのリンク（https://github.com/eukosh/youtube-kit/blob/main/PRIVACY.md）、承認済みドメイン github.com を入力します。これらがないと Google は公開できません。次に Audience で Publish app をクリックします。アプリが Testing の間は、登録済みのテストユーザーのみサインインでき、Google は7日後にログアウトさせます。
3. Clients で Desktop app タイプのクライアントを作成し、その JSON をダウンロードします。
4. ytk auth login --client-secrets path/to/client_secret.json を実行します。アプリが Google の確認を受けていないという警告が表示されますが、これは自分のアプリなので、Advanced をクリックし、次に Go to ytk (unsafe) をクリックします。

公開データ（検索、動画、チャンネル、再生リスト、コメント）は、API キーだけでも利用できます。同じプロジェクトで API キーを作成し、export YOUTUBE_API_KEY=... を実行するか、MCP サーバーの env に設定してください。キーがない場合、ytk はログインを通じて公開データを読み取ります。

ytk は、ログイン時点での各チャンネルのハンドルを記憶します。YouTube でチャンネル名を変更した後は、UC… ID で指定するか、そのチャンネルで ytk auth login を再度実行してください。

認証情報と config.toml はユーザー設定ディレクトリに保存されます（macOS では ~/Library/Application Support/youtube-kit/、Linux では ~/.config/youtube-kit/）。ytk auth status を実行すると正確なパスが表示されます。次の環境変数で上書きできます。

変数	用途
YOUTUBE_API_KEY	公開データ用 API キー
YOUTUBE_CLIENT_SECRETS	OAuth クライアント JSON のパス
YOUTUBE_TOKEN_DIR	保存されたログイン情報のディレクトリ（チャンネルごとに1ファイル）
YOUTUBE_CHANNEL	デフォルトで操作するチャンネル（UC… ID、@handle、または正確なタイトル）。ytk auth switch より優先されます
YOUTUBE_CONFIG_FILE	config.toml のパス（削除制限、更新チェック）
YTK_NO_UPDATE_CHECK	設定すると（空でも可）、新しいリリースがないか毎日確認しません

## エージェント向けに構築

• JSON を出力し、失敗時は終了コードで通知します。 各コマンドは標準出力に 1 つの JSON ドキュメントを出力します。失敗時は標準出力が空のままで、標準エラー出力の最終行は {"error": {"type": "not_found", "message": "..."}} となり、終了コードが種類を示します。2 は入力不正、3 は見つからない、4 は認証されていない、5 はクォータ超過、6 は禁止、7 はネットワーク、8 は確認が必要、9 は保護対象、10 はタイムアウト、1 はその他すべてです。スキルでは、それぞれに対してエージェントがどう対応すべきかを説明しています。ターミナルでは、色付きの JSON と通常の文章によるエラーが表示されます。
• 柔軟な入力。 ID または貼り付けた YouTube URL、チャンネルの @handles、日付や 90d のような期間を渡せます。
• クォータコストを事前に表示。 各コマンドの --help と各 MCP ツールの説明には、消費するクォータが記載されています。
• コアは 1 つです。 CLI と MCP サーバーは、同じコードの上に構築された薄いレイヤーであり、どちらか一方でも操作を実行できないとテストが失敗します。
• 削除を保護。 以下を参照してください。
• 更新のお知らせ。 ytk はバックグラウンドで 1 日 1 回 PyPI を確認し、新しいリリースがあると通知します。ターミナルでは出力後に、エージェントには {"update": ...} の標準エラー出力行で、MCP サーバーでは起動時の指示で通知されます。インストールするには ytk upgrade を実行します。config.toml の [updates] に check = false を設定するか、YTK_NO_UPDATE_CHECK=1 を設定すると確認を無効にできます。また、CI または NO_UPDATE_NOTIFIER が設定されている場合も無効になります。

削除

YouTube にはゴミ箱がなく、エージェントは間違えることがあります。そのため、動画、再生リスト、コメント、字幕トラックの削除は保護されています。

• 2 段階の手順。 最初の呼び出しでは何も削除されません。ターミナルには [y/N] の確認プロンプトが表示されます。エージェントには、対象の説明とともに終了コード 8 が返されるため、--confirm <id> を付けてコマンドを再実行する必要があります。これにより、承認の対象が削除するものと必ず一致します。

• 損害の上限。 再生回数が 100 回を超える動画、または公開状態でアップロードから 7 日を超えた動画は、ここから削除できません（終了コード 9）。その場合は YouTube Studio で削除してください。上限は config.toml に設定されています（保存場所は ytk auth status で確認できます）。

  [delete_protection]
  max_views = 100
  max_public_age_days = 7
  

• ハーネスによる承認。 削除のたびに、エージェントがユーザーに確認するようにしてください。Claude Code では、以下を .claude/settings.json に追加します。

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

• 冪等性。 すでに削除済みのものを削除しても、"already_gone": true として成功します。

この仕組みは誤操作を防ぎますが、意図的なエージェントを止めるものではありません。OAuth トークンを持つものは、API を直接呼び出せます。

クォータ

Google は各 Cloud プロジェクトに 1 日あたり 10,000 ユニットを付与しており、太平洋時間の午前 0 時にリセットされます。読み取りはリクエストごとに 1 ユニット、ほとんどの書き込みは 50 ユニット、保護された削除は 52 ユニット、字幕トラックの場合は 102 ユニットです（最初に対象を検索し、所有権を確認するため）。search とアップロードはこれらのユニットを消費しません。それぞれ 1 日あたり 100 回までで、検索結果 50 件のページごと、またはアップロードごとに 1 回として数えられます。ytk analytics と ytk impressions は、YouTube Analytics API と Reporting API の別個のクォータを使用します。

コントリビュート

開発環境のセットアップについては CONTRIBUTING.md を、変更内容については CHANGELOG.md を参照してください。セキュリティ上の問題は、SECURITY.md の説明に従って非公開で報告してください。

ライセンス

MIT。youtube-kit は Google または YouTube と提携しておらず、両社から承認を受けているものでもありません。YouTube は Google LLC の商標です。