youtube-mcp

youtube-mcp

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

产品亮点

大多数现有的 YouTube MCP 都使用 API 密钥调用 Data API v3，只能搜索视频、获取公开元数据，且为只读。这个项目使用 OAuth 2.0（Authorization Code + 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. 在 https://console.cloud.google.com 创建 Google Cloud 项目。名称随意（例如 youtube-mcp）。

3. 启用 API：

   • YouTube Data API v3
   • YouTube Analytics API

4. OAuth 同意屏幕： 选择 External，填写应用名称和支持邮箱。在 Scopes 中添加：

   • youtube.upload
   • youtube.force-ssl
   • yt-analytics.readonly

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

6. 创建 OAuth Client ID： Application type 选择 Desktop app。下载 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 端点。

配置

CLI 标志	环境变量	默认值	备注
--client-secret-file	YOUTUBE_CLIENT_SECRET_FILE	(none)	Google OAuth JSON 文件的路径
--client-id	YOUTUBE_CLIENT_ID	(none)	可替代密钥文件
--client-secret	YOUTUBE_CLIENT_SECRET	(none)	可替代密钥文件
--token-file	YOUTUBE_TOKEN_FILE	~/.config/youtube-mcp/token.json	刷新令牌存储位置
--host	MCP_HOST	0.0.0.0	绑定主机（仅 HTTP 模式）
--port	MCP_PORT	9120	绑定端口（仅 HTTP 模式）
--stdio	MCP_TRANSPORT=stdio	(unset)	通过 stdio 而非 HTTP 使用 MCP。由优先使用 stdio 的 MCP 客户端（Claude Desktop、mcp-inspector）作为子进程启动时使用。
--comfyui-url	COMFYUI_URL	(unset, bridge disabled)	桥接工具使用的 ComfyUI HTTP URL
(无标志)	COMFYUI_DEFAULT_CKPT	sd_xl_base_1.0.safetensors	桥接工具的默认 checkpoint

传输方式

服务器默认使用可流式传输的 HTTP（适用于 Claude Code、MetaMCP、原始 fetch）。传入 --stdio（或设置 MCP_TRANSPORT=stdio）即可切换到 stdio 模式，这是 Claude Desktop 和 MCP Inspector 等优先使用 stdio 的客户端所期望的模式：

// claude_desktop_config.json
{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "@miller-joe/youtube-mcp", "--stdio"],
      "env": {
        "YOUTUBE_CLIENT_SECRET_FILE": "/path/to/client_secret.json",
        "YOUTUBE_TOKEN_FILE": "/path/to/token.json"
      }
    }
  }
}

stdio 模式会跳过 OAuth 令牌预检 — 即使没有存储的令牌，服务器也会启动，并在调用工具时显示身份验证错误。在 HTTP 模式下运行一次 youtube-mcp --auth --client-secret-file <path>，以预先获取刷新令牌，然后再让 Claude Desktop 连接到它。

工具

视频

• 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（按时长 ≤60s 筛选）。
• get_shorts_analytics：查询仅限 Shorts 的 YouTube Analytics（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+。

路线图

已发布：

• 视频：列出、获取、更新元数据，以及通过标题匹配确认保护删除操作。
• 字幕：上传、列出、删除。
• Shorts：list_my_shorts（时长筛选）和 get_shorts_analytics（creatorContentType==SHORTS）。
• 播放列表：创建、添加视频。
• 评论：列出、回复、审核。
• 分析：频道分析查询。
• ComfyUI 缩略图桥接：generate_and_set_thumbnail。

计划中：

• 视频上传（video_upload），支持可恢复上传。
• Reporting API，用于批量导出历史数据。

许可证

MIT © Joe Miller

支持

如果这为你节省了时间，可以考虑支持开发：