youtube-kit

youtube-kit

面向 Agent 和用户打造的 YouTube 命令行工具（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

或者询问你的 Agent：“这个月我的哪些视频获得了最多观看次数？有没有等待审核的评论？”

在 Agent 中使用

技能：Claude Code、Codex、Cursor 和其他 Shell Agent

一个简短的技能可以教 Agent 使用命令行工具。只有在需要处理 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 工具引导你完成设置。

涵盖范围

类别	操作
分析	总计，或按日、月、视频、国家/地区、设备、操作系统、流量来源及其具体来源（搜索词、推荐视频、网站）、播放位置、年龄、性别、订阅状态、内容类型（长视频、Shorts、直播）或分享服务细分；视频观众留存率；按视频、内容类型、国家/地区或流量来源筛选
展示次数	缩略图展示次数和点击率，可查看总计、按日或按视频统计
视频	获取、类别、上传（支持断点续传并显示进度）、更新元数据、设置缩略图、等待处理完成、点赞或点踩、查看你的评分、删除
字幕	你的视频字幕稿，可使用你上传的字幕或 YouTube 自动生成的字幕，也可选择机器翻译；列出任意视频的字幕轨道；上传、替换、隐藏、删除
评论	列出（已发布、待审核、疑似垃圾内容）、回复、发布、回复评论、编辑、删除、批准、暂缓审核、拒绝、封禁作者
播放列表	列出、获取、查看项目、创建、更新、设置图片、添加、移除、移动、删除
频道	获取、近期活动、你已登录的频道、关于信息（简介、关键词、国家/地区、语言、预告片）、横幅、角标、主页版块
搜索	视频、频道和播放列表，可按频道或日期筛选
订阅	列出、订阅、取消订阅

未涵盖：本地化、直播和频道会员。ytk --help 会列出所有命令；技能 用一页内容和 jq 示例涵盖了这些命令。

频道与登录

ytk auth login 会连接一个频道。对其他每个频道（包括品牌频道）再次运行此命令；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 可为当前 Shell 或单个 MCP 服务设置默认频道。

为什么要使用你自己的 Google Cloud 客户端。 YouTube 每日 10,000 单位的配额属于 Cloud 项目。ytk 内置的客户端会让所有用户共用一份配额。使用你自己的客户端时，只有你的频道共用这份配额。

让 Agent 帮你完成设置。 ytk auth guide（通过 MCP 使用 setup_guide）会列出尚未完成的项目，并提供链接和需要填写的值。如果已登录 gcloud CLI，Agent 可以为你创建项目并启用 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 会记住你登录时各频道的 handle。在 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	存储登录信息的目录，每个频道对应一个文件
YOUTUBE_CHANNEL	默认操作的频道（UC… ID、@handle 或准确标题），会覆盖 ytk auth switch
YOUTUBE_CONFIG_FILE	config.toml 的路径（删除限制、更新检查）
YTK_NO_UPDATE_CHECK	设置此变量（即使值为空）：不再每日检查是否有新版

## 为 Agent 打造

• 输出 JSON，失败时返回退出码。 每条命令都会在 stdout 上打印一个 JSON 文档。失败时，stdout 保持为空，stderr 的最后一行是 {"error": {"type": "not_found", "message": "..."}}，退出码表示错误类型：2 表示输入错误，3 表示未找到，4 表示未获授权，5 表示超出配额，6 表示禁止，7 表示网络错误，8 表示需要确认，9 表示受保护，10 表示超时，1 表示其他错误。技能文档会告诉 Agent 应如何处理各种错误。在终端中，你会看到带颜色的 JSON 和普通句式的错误信息。
• 宽容的输入格式。 可以传入 ID 或粘贴的 YouTube URL、频道的 @handles，以及日期或类似 90d 的时间跨度。
• 预先说明配额开销。 每条命令的 --help 和每个 MCP 工具的描述都会说明其配额消耗。
• 共用核心。 CLI 和 MCP 服务是基于同一套代码构建的轻量封装，并且有一项测试会在任一方遗漏某项操作时失败。
• 删除操作设有防护。 详见下文。
• 更新通知。 ytk 每天会在后台检查一次 PyPI，并在有新版本时通知你：在终端中于输出后显示；对 Agent，则在 stderr 中显示为 {"update": ...}；在 MCP 服务中，则会在启动时写入说明。运行 ytk upgrade 即可安装更新。在 config.toml 的 [updates] 下设置 check = false，或设置 YTK_NO_UPDATE_CHECK=1，即可关闭检查；设置了 CI 或 NO_UPDATE_NOTIFIER 时也会自动关闭。

删除

YouTube 没有回收站，而且 Agent 也会出错。因此，删除视频、播放列表、评论和字幕轨道时都设有防护：

• 分两步操作。 首次调用不会删除任何内容。在终端中，你会看到 [y/N] 提示。Agent 会收到退出码 8 和目标说明，并且必须使用 --confirm <id> 再次运行命令，因此确认操作始终会明确指出要删除的具体对象。

• 限制损害范围。 浏览量超过 100 的视频，或已公开发布且上传时间超过 7 天的视频，一律无法在此处删除（退出码为 9）。请在 YouTube Studio 中删除。这些限制定义在 config.toml 中（运行 ytk auth status 可查看其位置）：

  [delete_protection]
  max_views = 100
  max_public_age_days = 7
  

• Harness 审批。 让 Agent 在每次删除前都先征求你的同意。在 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。

这能防止误操作，但无法阻止蓄意为之的 Agent。任何持有你的 OAuth 令牌的程序都可以直接调用 API。

配额

Google 为每个 Cloud 项目每天提供 10,000 个单位，并在太平洋时间午夜重置。每次读取请求消耗 1 个单位，大多数写入操作消耗 50 个单位，受防护的删除操作消耗 52 个单位；删除字幕轨道则消耗 102 个单位（因为会先查找目标并检查所有权）。search 和上传操作不消耗这些单位：两者各自每天有 100 次调用额度，搜索每页 50 条结果计一次，上传每次计一次。ytk analytics 和 ytk impressions 使用独立的 YouTube Analytics 和 Reporting API 配额。

贡献

有关开发环境的设置，请参阅 CONTRIBUTING.md；有关变更内容，请参阅 CHANGELOG.md。如需报告安全问题，请按照 SECURITY.md 中的说明私下提交。

许可证

MIT。youtube-kit 与 Google 或 YouTube 无关，也未获得其认可。YouTube 是 Google LLC 的商标。