youtube-mcp

YouTube MCP

一款本地优先的 MCP 服务，可让 AI 助手搜索 YouTube、管理你的频道并查看分析数据；在更改频道和内容前，会先征求你的批准。

YouTube MCP 是一个使用 TypeScript 编写的 Model Context Protocol 服务。它向 Claude Code、Claude Desktop、Cursor 和 Codex 等 MCP 客户端提供 79 个工具。它通过 stdio 在你自己的设备上运行，将 OAuth 令牌和工作数据保存在你的磁盘上，除非你主动要求，否则绝不会启动网络监听器。

任何会更改 YouTube 帐户的操作都必须经过预览、批准、执行流程。助手会先准确展示它准备执行的操作，只有在你批准预览中的确切更改后，操作才会执行。

快速开始

1. 获取密钥。 按照新手设置指南操作（公开研究需要 5 分钟，使用你自己的频道则约需 15 分钟）。
2. 在 Agent 中安装。 在在你的 AI Agent 中安装中选择适合你的选项。
3. 登录一次（仅适用于你自己的频道）：在帐户和创作者工具中运行 youtube-auth 命令。
4. 向 Agent 提问：“检查我的 YouTube 授权状态”，然后“搜索 YouTube 上有关 MCP 的演讲”。

功能

读取（无需帐户，只需 API 密钥）

• 搜索视频（可按排序方式、日期、时长、频道、地区和安全搜索筛选），查看热门内容，列出任意频道最近上传的视频，并查询视频和频道。
• 列出视频下的公开评论。
• 获取公开视频字幕稿（尽力而为；部分视频没有字幕稿）。

读取（通过 OAuth 访问你自己的帐户和频道）

• 你的频道、订阅内容，以及你频道中的评论串。
• 创作者分析：指定日期范围内的频道概览、热门视频和观众留存率，以及灵活的报告（按日统计的观看次数、流量来源、设备、国家/地区、人口统计等）。
• 你上传的视频、播放列表和播放列表项目、字幕轨道，以及评论审核队列。

写入（你自己的帐户；更改频道和内容需要预览并获得批准，观众操作需要 confirm: true）

• 上传：支持断点续传的视频上传，并可查看状态、恢复上传和取消上传。除非你明确要求发布，否则上传的视频为私享。
• 视频：更新标题、说明和其他元数据，并设置缩略图。
• 字幕：上传、更新、下载和删除字幕轨道。
• 播放列表：创建、更新、删除播放列表，以及添加、移除或重新排列项目。新建播放列表默认为私享。
• 评论和审核：回复评论、设置审核状态（包括封禁作者），以及删除你频道上的评论。
• 频道资料：编辑频道说明、关键词、国家/地区和默认语言。
• 订阅管理：查看订阅项及其订阅者数量和最近上传日期，然后在一次批准后批量移除订阅项。
• 帐户操作：订阅、取消订阅、为视频评分、发布顶级评论（这些操作需要明确提供 confirm: true）。

私人观看分析（仅限本地）

• 导入 Google Takeout 中的 YouTube 历史记录，并获取个人资料以及两个日期范围之间的趋势对比。数据保存在本地 SQLite 文件中。
• 保存本地内容筛选允许列表，并生成有限的待处理队列。服务绝不会将队列应用到你的帐户。

安全模型

写入工具经过设计，确保 AI 客户端不会在意料之外做出更改：

1. 预检。 youtube_preflight_* 工具会从 YouTube 读取最新状态、验证请求并返回精确预览。
2. 批准。 使用 confirm: true 调用单独的 youtube_approve（每种更改各有一个工具），将批准绑定到配置文件、频道、目标、请求的更改和最新状态。批准会过期。批准信息存储在本地，因此已批准的操作在过期前即使服务重启也会保留。
3. 执行。 写入工具只有在使用相同的已批准输入并设置 confirm: true 时才会运行。

更多防护措施，均可在代码中查看：

• 用户操作（youtube_subscribe、youtube_unsubscribe、youtube_rate_video）、youtube_create_comment 以及本地整理和重置工具都是单步写入：无需预检，但必须明确设置 confirm: true。
• 不会自动重试变更操作。对于结果不明确的操作，会通过读取来核实。
• 公开可见性、定时发布、合成媒体变更和封禁作者都需要明确设置更高权限标志。
• 删除评论前，必须确认该评论属于你选定的频道。
• 字幕下载绝不会覆盖现有路径，也不会跟随符号链接。
• 创作者工具会检查已登录的 Google 账号是否与配置的频道 ID 相匹配。
• 自动化测试绝不会执行实际变更。

完整详情请参阅 docs/README.md。

要求

• Node.js 22.13 或更高版本
• 一个已启用 YouTube Data API v3 的 Google Cloud 项目（创作者分析工具还需要启用 YouTube Analytics API）
• 用于公开读取的 YouTube Data API 密钥，以及用于账号和创作者工具的 OAuth 桌面客户端

在 AI Agent 中安装

无需发布到 npm。除 Claude Desktop 安装包自带一份副本外，以下所有方式都会通过 npx -y https://github.com/pratikgh0se/youtube-mcp/releases/download/v0.3.2/youtube-mcp-0.3.2.tgz --transport stdio 从 GitHub Release 附带的预构建 tarball 运行服务。使用 npx 的方式需要在 PATH 中安装 Node.js 22.13+。请先按照新手设置指南创建 Google 凭据（简要说明见：Google 凭据）。你至少需要一个 YouTube Data API 密钥。

Agent	一行安装命令
Claude Code	/plugin marketplace add pratikgh0se/youtube-mcp，然后运行 /plugin install youtube-mcp@youtube-mcp
Claude Desktop	从 Releases 下载 .mcpb 并双击
Codex CLI	codex mcp add youtube-mcp -- npx -y https://github.com/pratikgh0se/youtube-mcp/releases/download/v0.3.2/youtube-mcp-0.3.2.tgz --transport stdio
Gemini CLI	gemini extensions install https://github.com/pratikgh0se/youtube-mcp
Antigravity CLI	将服务添加到 ~/.gemini/config/mcp_config.json
Cursor	使用安装按钮，或编辑 .cursor/mcp.json
VS Code / Copilot	使用安装按钮，或编辑 .vscode/mcp.json
Windsurf	将服务添加到 mcp_config.json
Cline	将服务添加到 cline_mcp_settings.json，或让 Cline 使用 llms-install.md
Zed	添加 context_servers 条目
goose	运行 goose configure，或编辑 config.yaml
其他 Agent	参见 AGENTS.md 和 configs/generic-stdio.json

configs/ 中提供了适用于各客户端的现成文件。请按示例使用占位符，切勿将真实密钥粘贴到要提交的文件中。

首次启动时会下载预构建的 Release tarball 并安装其依赖项，普通网络连接下需要几秒钟。之后的启动会使用 npm 缓存。为避免网络较慢时客户端启动超时，建议先在终端中预热一次缓存：

npx -y https://github.com/pratikgh0se/youtube-mcp/releases/download/v0.3.2/youtube-mcp-0.3.2.tgz --version

Claude Code

claude plugin marketplace add pratikgh0se/youtube-mcp
claude plugin install youtube-mcp@youtube-mcp

也可以在 Claude Code 中运行：/plugin marketplace add pratikgh0se/youtube-mcp，然后运行 /plugin install youtube-mcp@youtube-mcp。Claude Code 会提示你输入 API 密钥（存储在操作系统的凭据存储区中）以及另外四项设置：OAuth 客户端文件、配置文件名称和频道 ID 为必填项，状态目录为可选项（留空则使用 ~/.youtube-mcp）。该插件仅保存配置，服务本身仍通过 npx 运行。

Claude Desktop

从 GitHub Releases 下载 youtube-mcp-<version>.mcpb（适用于 macOS、Windows 和 Linux 的通用安装包）并双击。Claude Desktop 会显示安装对话框并提示你输入 API 密钥。安装包内含服务，因此运行时无需使用 npx。

如果不想使用安装包，也可以采用备用方案：将 configs/claude-desktop.json 添加到 claude_desktop_config.json，然后重新启动。首次启动时会下载软件包，可能需要几秒钟。

{
  "mcpServers": {
    "youtube-mcp": {
      "command": "npx",
      "args": ["-y", "https://github.com/pratikgh0se/youtube-mcp/releases/download/v0.3.2/youtube-mcp-0.3.2.tgz", "--transport", "stdio"],
      "env": { "YOUTUBE_API_KEY": "<your-youtube-api-key>" }
    }
  }
}

Codex CLI

codex mcp add youtube-mcp --env YOUTUBE_API_KEY=<your-youtube-api-key> -- npx -y https://github.com/pratikgh0se/youtube-mcp/releases/download/v0.3.2/youtube-mcp-0.3.2.tgz --transport stdio

这会将密钥存储在 ~/.codex/config.toml 中。若要避免将密钥写入文件，请改用 configs/codex.toml。它通过 env_vars 传递 shell 中的变量（Codex 不会展开 ${VAR}），并将 startup_timeout_sec = 180 设为启动超时时间，因为默认的 10 秒比首次运行 npx 所需时间短。

[mcp_servers.youtube-mcp]
command = "npx"
args = ["-y", "https://github.com/pratikgh0se/youtube-mcp/releases/download/v0.3.2/youtube-mcp-0.3.2.tgz", "--transport", "stdio"]
env_vars = ["YOUTUBE_API_KEY"]
startup_timeout_sec = 180

Gemini CLI

gemini extensions install https://github.com/pratikgh0se/youtube-mcp

Gemini 会提示你输入 API 密钥（保存在系统密钥链中，必填）、OAuth 客户端文件、配置文件名称和频道 ID（频道工具所需；请参阅设置指南）。之后可通过 gemini extensions config youtube-mcp 修改。纯 settings.json 配置项见 configs/gemini-settings.json。

注意：Google 已于 2026-06-18 停止向 AI Pro、Ultra 和免费个人用户提供 Gemini CLI。付费 API 密钥用户和企业用户仍可使用（来源）。其他用户请使用下方的 Antigravity CLI。

Antigravity CLI

将以下内容添加到 ~/.gemini/config/mcp_config.json（全局）或 <workspace>/.agents/mcp_config.json。也可在 configs/antigravity.json 中找到。

{
  "mcpServers": {
    "youtube-mcp": {
      "command": "npx",
      "args": ["-y", "https://github.com/pratikgh0se/youtube-mcp/releases/download/v0.3.2/youtube-mcp-0.3.2.tgz", "--transport", "stdio"],
      "env": { "YOUTUBE_API_KEY": "<your-youtube-api-key>" }
    }
  }
}

Cursor

此按钮会从 shell 环境中读取 YOUTUBE_API_KEY。也可以将 configs/cursor.json 添加到 .cursor/mcp.json（或 ~/.cursor/mcp.json）中。它使用 ${env:YOUTUBE_API_KEY}，因此不会将密钥写入文件。

VS Code / Copilot

此按钮会在不提供密钥的情况下安装服务。之后可通过服务的 env 添加密钥，或使用下方会提示你输入密钥的文件。在终端中运行：

code --add-mcp '{"name":"youtube-mcp","type":"stdio","command":"npx","args":["-y","https://github.com/pratikgh0se/youtube-mcp/releases/download/v0.3.2/youtube-mcp-0.3.2.tgz","--transport","stdio"]}'

或者，将 configs/vscode.json 保存为 .vscode/mcp.json。VS Code 会在首次启动时提示你输入密钥（password: true），并安全地保存密钥。

{
  "inputs": [
    { "type": "promptString", "id": "youtube-api-key", "description": "YouTube Data API v3 key", "password": true }
  ],
  "servers": {
    "youtube-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "https://github.com/pratikgh0se/youtube-mcp/releases/download/v0.3.2/youtube-mcp-0.3.2.tgz", "--transport", "stdio"],
      "env": { "YOUTUBE_API_KEY": "${input:youtube-api-key}" }
    }
  }
}

Windsurf

使用 configs/windsurf.json（它会读取 ${env:YOUTUBE_API_KEY}）。当前 Devin 文档指定文件路径为 ~/.config/devin/mcp_config.json（Windows：%APPDATA%\devin\mcp_config.json）。许多指南仍使用旧路径 ~/.codeium/windsurf/mcp_config.json。只有前者得到供应商文档确认，因此如果一个路径无法加载，请尝试另一个。

Cline

打开 MCP Servers 面板，选择 Configure，然后选择“Configure MCP Servers”，并添加 configs/cline.json。Cline CLI 的文件路径为 ~/.cline/data/settings/cline_mcp_settings.json。Cline 未说明是否支持环境变量插值，因此密钥需要以明文值的形式写入该文件。也可以让 Cline 从 llms-install.md 安装。

Zed

将 configs/zed.json 添加到 Zed 设置中（运行 zed: open settings file 操作）。Zed 将该映射称为 context_servers。密钥需要以明文值的形式写入。

goose

运行 goose configure，选择 Add Extension，然后选择 Command-Line Extension，并输入 npx -y https://github.com/pratikgh0se/youtube-mcp/releases/download/v0.3.2/youtube-mcp-0.3.2.tgz --transport stdio，同时将密钥设为环境变量。或者，将 configs/goose.yaml 添加到 ~/.config/goose/config.yaml。深层链接形式（粘贴到浏览器或 open 中）只会设置命令，因此请之后再添加密钥：

goose://extension?cmd=npx&arg=-y&arg=https%3A%2F%2Fgithub.com%2Fpratikgh0se%2Fyoutube-mcp%2Freleases%2Fdownload%2Fv0.3.2%2Fyoutube-mcp-0.3.2.tgz&arg=--transport&arg=stdio&id=youtube-mcp&name=YouTube%20MCP&description=Search%20YouTube%20and%20manage%20your%20channel%20with%20approval%20for%20every%20change

其他 Agent

任何可启动 stdio MCP 服务的客户端都可以使用 configs/generic-stdio.json。configs/ 中也有适用于 OpenCode、OpenClaw 和 Hermes 的模板。为用户安装此工具的 Agent 应阅读 AGENTS.md。

账号和创作者工具：授权一次即可

公共工具只需要 API 密钥。对于账号和创作者工具，请将 第 2 步中的 OAuth 客户端文件、个人资料名称和频道 ID 添加到客户端配置中，然后在终端中使用相同的值运行一次性 Google 登录：

YOUTUBE_OAUTH_CLIENT_SECRET_FILE=/absolute/path/to/client_secret.json \
YOUTUBE_MCP_PROFILE_ID=creator-main \
npx -y https://github.com/pratikgh0se/youtube-mcp/releases/download/v0.3.2/youtube-mcp-0.3.2.tgz youtube-auth

这会打开浏览器，在本地 127.0.0.1 回调地址进行 Google 授权，并请求 youtube、youtube.force-ssl 和 yt-analytics.readonly 作用域。令牌会按个人资料存储在 ~/.youtube-mcp 中，之后的调用会在后台自动刷新令牌。如果撤销了访问权限，请重新运行。

Google 凭据

1. 创建凭据

初次使用 Google Cloud？请参阅分步新手设置指南。简要步骤如下：

在 Google Cloud 控制台中：

1. 创建或选择一个项目，然后启用 YouTube Data API v3 和 YouTube Analytics API。
2. 创建一个 API 密钥。公共工具只需此密钥。
3. 对于账号和创作者工具，请配置 OAuth 同意屏幕（应用处于测试状态时，将自己添加为测试用户），然后创建类型为 Desktop app 的 OAuth 客户端 ID，并下载其 JSON 文件。

2. 设置环境变量

将这些变量填入客户端配置（请参阅在 AI Agent 中安装），或者从代码检出目录运行时，将 .env.example 复制为 .env（该文件已加入 git 忽略列表）。切勿提交真实值。

变量	用途	含义
YOUTUBE_API_KEY	公共工具	你的 YouTube Data API 密钥。
YOUTUBE_OAUTH_CLIENT_SECRET_FILE	账号和创作者工具	Desktop OAuth 客户端 JSON 文件的绝对路径。
YOUTUBE_MCP_PROFILE_ID	创作者工具	自选名称，例如 creator-main。用于按个人资料隔离本地状态。
YOUTUBE_MCP_CHANNEL_ID	创作者工具	你的频道 ID（以 UC 开头）。登录账号必须拥有该频道。
YOUTUBE_MCP_STATE_DIR	可选	本地状态的存储位置。默认为 ~/.youtube-mcp。Claude Code 插件和 Gemini 扩展会提示你填写此项（留空表示使用默认值）。无论在哪里，空值都会被视为未设置。

从本地代码检出目录运行

用于开发，或在不使用 npx 的情况下运行：

git clone https://github.com/pratikgh0se/youtube-mcp.git
cd youtube-mcp
npm ci
npm run build   # npm ci already builds via the prepare script
npm run auth    # one-time Google sign-in, same as the npx youtube-auth command

使用绝对路径将客户端指向代码检出目录：

{
  "mcpServers": {
    "youtube-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/youtube-mcp/bin/youtube-mcp.mjs", "--transport", "stdio"],
      "env": {
        "YOUTUBE_API_KEY": "your-api-key",
        "YOUTUBE_OAUTH_CLIENT_SECRET_FILE": "/absolute/path/to/client_secret.json",
        "YOUTUBE_MCP_PROFILE_ID": "creator-main",
        "YOUTUBE_MCP_CHANNEL_ID": "UC..."
      }
    }
  }
}

更多模板（每个客户端各一个）位于 configs/ 中。这些模板会使用 npx -y https://github.com/pratikgh0se/youtube-mcp/releases/download/v0.3.2/youtube-mcp-0.3.2.tgz --transport stdio 启动服务。要改用你的代码检出目录，请将命令改为 node，并使用上面的路径。

可选：本地 HTTP

PORT=3000 node bin/youtube-mcp.mjs --transport http

此配置仅绑定到 127.0.0.1。请勿将其暴露到互联网。

提示词示例

• “在 YouTube 上搜索近期关于 Model Context Protocol 的演讲，并总结排名前三的内容。”
• “获取此视频的文字稿，并列出要点。”
• “显示我频道过去 90 天播放量最高的 10 个视频，以及观众在最近一个视频中的流失位置。”
• “预览 /Users/me/videos/demo.mp4 中的私人上传视频，标题为 ‘Demo’，然后等我批准。”
• “创建一个名为 ‘To review’ 的私人播放列表，并将这五个视频添加进去。请先向我展示预览。”
• “列出我最新视频中尚未回复的评论，并起草回复供我批准。”
• “导入我的 Takeout 观看记录，并比较我 1 月和 6 月观看的内容。”

工具

共有 79 个工具，按领域分组。标记为“预检并批准”的工具需要使用上述三步流程。

区域	工具
公开读取（7）	youtube_search（筛选条件：order、publishedAfter/publishedBefore、videoDuration、channelId、regionCode、relevanceLanguage、safeSearch、pageToken；100 个配额单位）、youtube_trending（按地区和类别列出最受欢迎的视频，1 个单位）、youtube_list_channel_videos（按频道 ID 或 @handle 列出近期上传的视频及其统计数据，每页约 3 个单位）、youtube_get_video、youtube_get_channel、youtube_get_comments、youtube_get_transcript
你的账号（9）	读取：youtube_my_account、youtube_list_subscriptions（分页；details: true 会添加 subscriberCount、videoCount 和 lastUploadAt，每个返回的频道约额外消耗 1 个配额单位）、youtube_list_channel_comment_threads。写入（confirm: true）：youtube_subscribe、youtube_unsubscribe、youtube_rate_video、youtube_create_comment（仅限你频道拥有的视频；其他视频会因 ownership_required 而被拒绝）。批量取消订阅（预检并批准）：youtube_preflight_unsubscribe_many、youtube_unsubscribe_many（最多 100 个订阅，每个 50 个配额单位；单项结果为 removed、already_gone、failed 或 unknown（结果不确定：使用 youtube_list_subscriptions 进行核对）；配额耗尽时会提前停止）
创作者分析（4）	youtube_creator_overview、youtube_creator_top_videos、youtube_creator_retention、youtube_creator_report（允许列表中的 YouTube Analytics 报告：选择指标、维度、筛选条件和排序；无效组合会提前拒绝）
频道资料（2）	youtube_preflight_update_channel、youtube_update_channel：编辑你频道的描述、关键词、国家/地区和默认语言（预检并批准；其他品牌设置会保留）
创作者读取（10）	youtube_list_owned_videos、youtube_get_owned_video、youtube_list_video_categories、youtube_list_playlists、youtube_get_playlist、youtube_list_playlist_items、youtube_list_caption_tracks、youtube_list_moderation_comments、youtube_get_moderation_comment、youtube_find_comment_reply
上传（7）	youtube_preflight_upload、youtube_upload_video、youtube_get_upload_status、youtube_preflight_resume_upload、youtube_resume_upload、youtube_preflight_cancel_upload、youtube_cancel_upload
视频元数据、归档和缩略图（6）	youtube_preflight_update_metadata、youtube_update_metadata、youtube_preflight_archive_video、youtube_archive_video、youtube_preflight_set_thumbnail、youtube_set_thumbnail
字幕（7）	youtube_preflight_caption_upload、youtube_upload_caption、youtube_preflight_caption_update、youtube_update_caption、youtube_download_caption（无需批准；会在 <state dir>/downloads/ 中写入一个以 fileName 命名的新文件，并返回其路径）、youtube_preflight_caption_delete、youtube_delete_caption
播放列表（12）	youtube_preflight_create_playlist、youtube_create_playlist、youtube_preflight_update_playlist、youtube_update_playlist、youtube_preflight_delete_playlist、youtube_delete_playlist、youtube_preflight_add_playlist_item、youtube_add_playlist_item、youtube_preflight_remove_playlist_item、youtube_remove_playlist_item、youtube_preflight_reorder_playlist_item、youtube_reorder_playlist_item
评论和审核（6）	youtube_preflight_reply_to_comment、youtube_reply_to_comment、youtube_preflight_set_comment_moderation_status、youtube_set_comment_moderation_status、youtube_preflight_delete_comment、youtube_delete_comment
批准（1）	youtube_approve：通过 approvalId 批准任何待处理的预览，并显示其类型、目标和确切变更
本地观看分析（7）	youtube_import_takeout、youtube_consumption_profile、youtube_consumption_trends、youtube_save_curation_policy、youtube_save_curation_candidate、youtube_propose_consumption_queue、youtube_reset_consumption_data
状态（1）	youtube_auth_status

隐私与安全

• OAuth 刷新令牌存储在本机的 ~/.youtube-mcp（或 YOUTUBE_MCP_STATE_DIR）下，文件仅对用户开放权限。
• 操作审批、上传恢复状态以及从 Takeout 导出的 SQLite 数据库（consumption.sqlite）都保存在同一目录中。Takeout 导入器不会向 YouTube 发送数据。
• 你的 Google 凭据只会发送给 Google 的 API。公开的字幕工具使用 youtube-transcript 包从 YouTube 获取字幕。
• 默认传输方式为 stdio。可选的 HTTP 传输仅绑定到 127.0.0.1。
• 切勿提交 .env、OAuth 客户端 JSON、令牌状态或 Takeout 导出文件。.gitignore 已排除 .env 文件。
• 运行此服务会让 AI 客户端在你授予的权限范围内访问你的 YouTube 账号。批准前请逐一查看预览。
• 如需报告漏洞，请遵循 SECURITY.md 并使用 GitHub 的私密报告渠道。请勿创建公开议题。

开发

npm ci
npm run lint            # type check the source
npm run typecheck:tests # type check the tests
npm test                # vitest, fully offline (214 tests)
npm run build           # compile to dist/
npm run smoke:read-only # offline by default; set YOUTUBE_LIVE_SMOKE=1 with an API key for one live read
npm run dev:stdio       # run from source over stdio

持续集成（.github/workflows/verify.yml）会在 Node 22 上运行相同的检查。请参阅 docs/CHANGELOG.md，了解更改内容。

贡献

欢迎提交议题和拉取请求。提交拉取请求前，请运行 npm run lint、npm run typecheck:tests 和 npm test，为任何行为变更添加测试，并确保写入操作必须经过预检和审批流程。切勿在议题、测试或夹具中包含真实凭据、令牌或个人数据。

许可证

MIT (c) 2026 Pratik Ghose