Skip to main content
Glama

youtube-mcp

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

youtube-mcp MCP server

GitHub Sponsors Ko-fi

核心优势

大多数现有的 YouTube MCP 使用 Data API v3 的 API 密钥,仅能搜索视频、获取公开元数据,且为只读。本项目使用 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。完成。

Related MCP server: yt-fetch

安装

# 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 频道。 请使用个人账号,不要使用可能会丢失的 Workspace 账号。

  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. 保持在 测试 (Testing) 模式。将您自己添加为 测试用户(必需)。作为项目所有者,您的刷新令牌不会过期。

  6. 创建 OAuth 客户端 ID: 应用类型 = 桌面应用 (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

(无)

Google OAuth JSON 文件路径

--client-id

YOUTUBE_CLIENT_ID

(无)

客户端 ID(替代 secret 文件)

--client-secret

YOUTUBE_CLIENT_SECRET

(无)

客户端密钥(替代 secret 文件)

--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

(未设置)

通过 stdio 而非 HTTP 进行 MCP 通信。当被 stdio 优先的 MCP 客户端(如 Claude Desktop, mcp-inspector)作为子进程启动时使用。

--comfyui-url

COMFYUI_URL

(未设置,桥接禁用)

用于桥接工具的 ComfyUI HTTP URL

(无参数)

COMFYUI_DEFAULT_CKPT

sd_xl_base_1.0.safetensors

桥接工具的默认检查点

传输方式

服务器默认使用 streamable 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 令牌预检 — 即使没有存储的令牌,服务器也会启动,并在工具调用时抛出认证错误。在将 Claude Desktop 指向它之前,请先在 HTTP 模式下运行 youtube-mcp --auth --client-secret-file <path> 以生成刷新令牌。

工具

视频

  • 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 分析查询 (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

支持

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

GitHub Sponsors Ko-fi

Available Tools

15 tools
add_to_playlistB

Add a video to an existing playlist. Both playlist_id and video_id are YouTube IDs (not URLs).

Inputs: playlist_id (required), video_id (required).

create_playlistB

Create a new playlist on the authenticated channel. Default privacy is 'private'.

Inputs: title (required), description, privacy_status.

delete_captionA

Delete a caption track by ID. Use list_captions to find the track ID first.

Inputs: caption_id (required).

delete_videoA

Permanently delete a video. Requires confirm_video_title to match the video's current title exactly — guards against deleting the wrong video by ID. Deletion is irreversible.

Inputs: video_id (required), confirm_video_title (required).

get_shorts_analyticsA

Query YouTube Analytics restricted to Shorts for the authenticated channel. Applies filters=creatorContentType==SHORTS on top of the usual start_date/end_date/metrics/dimensions knobs.

Inputs: start_date (required), end_date (required), metrics, dimensions, +2 more.

get_videoA

Fetch full details for one video by ID — snippet, status, statistics, duration.

Inputs: video_id (required).

list_captionsA

List caption tracks on a video with their language, name, status, and whether they are drafts.

Inputs: video_id (required).

list_commentsB

List top-level comment threads on a video (newest first). Returns comment IDs, authors, text, and like counts.

Inputs: video_id (required), max_results.

list_my_shortsA

List your recent Shorts — scans the most recent uploads and filters to videos ≤60s. Useful when the Data API doesn't expose a direct Shorts filter.

Inputs: max_candidates.

list_my_videosA

List videos on the authenticated channel (newest first via the uploads playlist). Returns video IDs, titles, view counts, and privacy status.

Inputs: max_results, page_token.

moderate_commentA

Change the moderation status of a comment: heldForReview (hide pending approval), published (approve), or rejected (delete).

Inputs: comment_id (required), moderation_status (required).

query_channel_analyticsA

Query YouTube Analytics for the authenticated channel. Returns tabular data — useful for views/watch-time/retention/traffic-source reports. Date-ranged and optionally grouped by dimensions.

Inputs: start_date (required), end_date (required), metrics, dimensions, +3 more.

reply_to_commentB

Reply to a top-level comment. Requires youtube.force-ssl scope.

Inputs: parent_id (required), text (required).

update_video_metadataA

Update a video's metadata — title, description, tags, category, or privacy. Only provide fields you want changed.

Inputs: video_id (required), title, description, tags, +2 more.

upload_captionA

Upload a caption track (SRT or WebVTT) to a video. Creates a new track — use a distinct name per language/track, or is_draft=true while iterating.

Inputs: video_id (required), language (required), caption_text (required), name, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 15 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action. Analytics tools are clearly differentiated (general vs Shorts-specific), and video list vs Shorts list is scoped by content type. Comments, captions, and playlists each have their own dedicated tools with no overlap.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern (list_, get_, create_, update_, delete_, upload_, reply_to_, add_to_, moderate_, query_). There are no mixed conventions or cryptic abbreviations, making the naming predictable and easy to reason about.

    Tool Count5/5

    15 tools cover a broad YouTube management surface without feeling bloated. The set is well-scoped for the server's purpose—video, playlist, caption, comment, and analytics operations—and each tool has a clear role within that scope.

    Completeness3/5

    The coverage has significant gaps, especially for playlists: there is no way to list, retrieve, delete, or remove items from playlists, creating dead ends after creation. Caption updates are also absent (only create and delete), although video CRUD and comment moderation are well covered.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers