youtube-mcp

面向频道所有者的 OAuth 认证 YouTube MCP — 编辑视频元数据、回复并审核评论、管理播放列表、查询频道分析，并通过 ComfyUI 桥接功能生成并设置 AI 缩略图。它超越了该领域常见的只读 Data API v3 封装。

MCP Server Series 的一部分。

简介

大多数现有的 YouTube MCP 使用 API 密钥调用 Data API v3 — 仅限于搜索视频、获取公开元数据和只读操作。本项目使用 OAuth 2.0 (授权码 + PKCE)，因此它实际上可以写入您的频道：更新视频标题/描述/标签、回复评论、审核垃圾信息、管理播放列表。此外，它还调用独立的 YouTube Analytics API 获取频道统计数据，并且 — 核心工具 — 通过 ComfyUI 生成缩略图，并通过一次 MCP 调用将其推送到 YouTube。

Claude, use generate_and_set_thumbnail on video abc123:
  prompt: "cyberpunk hacker at keyboard, neon blue and pink, high contrast"

→ ComfyUI 渲染 1280×720 → youtube-mcp 获取字节流 → POST 到 thumbnails.set。完成。

安装

# npx — no install
npx @miller-joe/youtube-mcp --help

# Docker
docker run -p 9120:9120 \
  -e YOUTUBE_CLIENT_ID=... \
  -e YOUTUBE_CLIENT_SECRET=... \
  -e YOUTUBE_TOKEN_FILE=/token/token.json \
  -v $PWD/token:/token \
  ghcr.io/miller-joe/youtube-mcp:latest

设置 — Google Cloud 一次性配置（约 10 分钟）

1. Google 账号 + YouTube 频道 — 请使用个人账号，不要使用可能丢失的办公账号。

2. Google Cloud 项目，访问 https://console.cloud.google.com — 随意命名（例如 youtube-mcp）。

3. 启用 API：

   • YouTube Data API v3

   • YouTube Analytics API

4. OAuth 同意屏幕 — 选择“外部”，填写应用名称、支持邮箱；在“范围 (Scopes)”中添加：

   • youtube.upload

   • youtube.force-ssl

   • yt-analytics.readonly

5. 保持在 测试 模式。将您自己添加为 测试用户（必需）。作为项目所有者，您的刷新令牌不会过期。

6. 创建 OAuth 客户端 ID： 应用类型 = 桌面应用。下载 JSON 文件。

7. 运行交互式认证流程：

   npx @miller-joe/youtube-mcp --auth --client-secret-file ./client_secret.json

   浏览器会打开 → 您登录绑定 YouTube 频道的 Google 账号 → 授予请求的权限范围。成功后，刷新令牌将保存到 ~/.config/youtube-mcp/token.json。

8. 启动服务器：

   npx @miller-joe/youtube-mcp --client-secret-file ./client_secret.json

   或者通过环境变量提供客户端凭据：YOUTUBE_CLIENT_SECRET_FILE，或 YOUTUBE_CLIENT_ID + YOUTUBE_CLIENT_SECRET。

连接 MCP 客户端

claude mcp add --transport http youtube http://localhost:9120/mcp

或者将您的 MCP 网关指向 Streamable HTTP 端点。

配置

工具

视频

• list_my_videos — 分页列出已认证频道的上传视频

• get_video — 获取单个视频的详细信息

• update_video_metadata — 更新标题 / 描述 / 标签 / 分类 / 隐私设置

• delete_video — 永久删除视频。需要 confirm_video_title 与当前标题完全匹配，以防止误删。

字幕

• list_captions — 列出视频的字幕轨道（语言、名称、状态、草稿标记）

• upload_caption — 上传 SRT 或 WebVTT 字幕轨道到视频

• delete_caption — 删除字幕轨道

Shorts

• list_my_shorts — 在最近上传中查找 Shorts（按 ≤60 秒时长过滤）

• get_shorts_analytics — 仅限 Shorts 的 YouTube 分析查询 (creatorContentType==SHORTS)

播放列表

• create_playlist — 创建播放列表（默认为私有）

• add_to_playlist — 将视频添加到现有播放列表

评论

• list_comments — 获取视频的顶级评论线程

• reply_to_comment — 回复顶级评论

• moderate_comment — 保持 / 批准 / 拒绝评论

分析

• query_channel_analytics — 带日期范围、可选维度和过滤器的指标查询

桥接 (当配置了 COMFYUI_URL 时)

• generate_and_set_thumbnail — 通过 ComfyUI 生成缩略图并一次性设置到视频上

配额说明

YouTube Data API 免费层级 = 10,000 单位/天。关键操作成本：

• videos.list, commentThreads.list — 每个 1 单位

• videos.update, comments.insert, thumbnails.set — 每个 50 单位

• videos.insert (上传) — 1,600 单位 → 免费层级每天约可上传 6 个视频

大多数创作者运营工作流都在免费额度内。

架构

┌────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  MCP client    │────▶│  youtube-mcp     │────▶│  YouTube APIs   │
│  (Claude etc.) │◀────│  (this server)   │◀────│  (Data/Analytics)│
└────────────────┘     └────────┬─────────┘     └─────────────────┘
                                │
                                │ (bridge tools only)
                                ▼
                       ┌──────────────────┐
                       │  ComfyUI         │
                       │  (txt2img)       │
                       └──────────────────┘

OAuth 刷新令牌在本地缓存，并在过期前及时刷新。桥接工具在内部从 ComfyUI 下载图像字节 — ComfyUI 无需公开可访问。

开发

git clone https://github.com/miller-joe/youtube-mcp
cd youtube-mcp
npm install
npm run dev
npm run build
npm test

需要 Node 20+。

路线图

• [x] 视频列表 / 获取 / 更新元数据

• [x] 播放列表创建 + 添加视频

• [x] 评论列表 / 回复 / 审核

• [x] 频道分析查询

• [x] ComfyUI 缩略图桥接 (generate_and_set_thumbnail)

• [x] 字幕上传 + 列表 + 删除 (upload_caption, list_captions, delete_caption)

• [x] 带标题匹配确认保护的视频删除

• [x] Shorts 人体工程学：list_my_shorts（时长过滤）+ get_shorts_analytics (creatorContentType==SHORTS)

• [ ] 视频上传 (video_upload) — 支持断点续传

• [ ] 用于批量历史数据导出的报告 API

许可证

MIT © Joe Miller

支持

如果这为您节省了时间，请考虑支持开发：