YouTube MCP

YouTube MCP

YouTube MCP 允许 MCP 客户端读取 YouTube 视频元数据、字幕转录文本、评论和搜索结果。默认情况下，无需 YouTube API 密钥或账号；也可选用官方 YouTube Data API 提供程序，通过 API 密钥提供元数据、评论和搜索功能。

同时支持 stdio（本地）和 Streamable HTTP（VPS／远程）传输方式。

访问方式

这是一个独立的非官方开源项目，与 YouTube 或 Google 无关，也未获得其认可或赞助。

• 默认的 innertube 提供程序通过 youtubei.js 提供元数据、评论和搜索功能，使用非官方／内部 YouTube 接口，无需 YouTube Data API 密钥。非官方访问方式可能发生变化、失效、受到限制或被屏蔽。
• 选择 YT_PROVIDER=api 并提供自己的 YOUTUBE_API_KEY，即可为这三种工具使用官方 YouTube Data API v3。
• 无论 YT_PROVIDER 的值是什么，字幕工具始终使用 youtube-transcript-plus。字幕获取仍属于非官方方式，不使用官方 Data API 路径或你的 API 密钥。

用户有责任自行判断访问方式是否适合其用途，并遵守适用的服务条款和法律。有关工具／后端的对应关系、BYOK 设置、限制和软件许可证，请参阅访问方式与服务条款。

功能

工具	描述
search_youtube	搜索视频，可按上传日期和受欢迎程度筛选
get_video_info	视频元数据：标题、频道、描述、时长、观看次数、点赞数、上传日期、标签
get_video_comments	评论串，包含作者信息、点赞数以及 YouTube 提供的回复
get_video_transcript	带时间戳的字幕转录文本（人工字幕和自动生成字幕）
get_transcript_languages	列出可用的人工字幕和自动生成字幕语言
get_server_info	服务版本、当前使用的提供程序，以及为各工具提供服务的后端

要求

• Node.js 22 或更高版本。CI 检查 Node 22.21.0 和 Node 24。

默认无需 YouTube API 密钥。 默认的 innertube 提供程序使用 youtubei.js（非官方／内部 YouTube 接口）获取视频信息、评论和搜索结果。字幕始终使用 youtube-transcript-plus。两者均无需 API 密钥或身份验证。有关可选的官方 API，请参阅提供程序。

快速开始

MCP 客户端可以直接运行已发布的软件包，无需克隆：

npx -y @granitebps/youtube-mcp

服务使用 stdio。请将 stdout 专用于 MCP 通信。

从克隆的仓库运行

要开发服务或直接使用克隆的仓库：

git clone https://github.com/granitebps/youtube-mcp.git
cd youtube-mcp
npm ci
npm run build

将 MCP 客户端指向已编译的入口文件：

node /absolute/path/to/youtube-mcp/dist/index.js

每次修改源代码后运行 npm run build。不要将 src 或 npm run dev 用作客户端的 stdio 命令；构建输出写入 stdout 可能会破坏 MCP 消息。

客户端配置

每个示例都先使用 npm 软件包，再提供对应的本地配置。将 /absolute/path/to/youtube-mcp 替换为克隆仓库的路径。可以将配置中的设置作为环境变量添加。

Claude

将 npm 包添加到 Claude Code：

claude mcp add youtube -- npx -y @granitebps/youtube-mcp

对于本地构建：

claude mcp add youtube -- node /absolute/path/to/youtube-mcp/dist/index.js

Claude Code 默认使用本地作用域。在 youtube 前添加 --scope user，即可让服务器在所有项目中可用。

Claude Desktop 会从同一配置文件读取服务器：claude_desktop_config.json（macOS 上的路径为 ~/Library/Application Support/Claude/claude_desktop_config.json）。编辑文件后，重启应用。

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "@granitebps/youtube-mcp"]
    }
  }
}

对于本地构建，将 command 和 args 替换为：

{
  "command": "node",
  "args": ["/absolute/path/to/youtube-mcp/dist/index.js"]
}

Codex

将 npm 包添加到 ~/.codex/config.toml，或添加到受信任项目中的 .codex/config.toml：

[mcp_servers.youtube]
command = "npx"
args = ["-y", "@granitebps/youtube-mcp"]

对于本地构建：

[mcp_servers.youtube]
command = "node"
args = ["/absolute/path/to/youtube-mcp/dist/index.js"]

编辑文件后，重启 Codex。

OpenCode

将 npm 包添加到 opencode.json 或 opencode.jsonc：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "youtube": {
      "type": "local",
      "command": ["npx", "-y", "@granitebps/youtube-mcp"],
      "enabled": true
    }
  }
}

对于本地构建，将 command 数组替换为：

{
  "command": ["node", "/absolute/path/to/youtube-mcp/dist/index.js"]
}

Cursor

将 npm 包添加到项目中的 .cursor/mcp.json，或添加到 ~/.cursor/mcp.json 以供全局使用：

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "@granitebps/youtube-mcp"]
    }
  }
}

对于本地构建，将 command 和 args 替换为：

{
  "command": "node",
  "args": ["/absolute/path/to/youtube-mcp/dist/index.js"]
}

GitHub Copilot（VS Code）

添加到 VS Code 的 settings.json：

{
  "mcp": {
    "servers": {
      "youtube": {
        "command": "npx",
        "args": ["-y", "@granitebps/youtube-mcp"]
      }
    }
  }
}

---

VPS 部署（Streamable HTTP）

对于远程部署，服务器会使用 Streamable HTTP 传输（当前的 MCP 标准，取代已弃用的 SSE 传输）作为持久 HTTP 服务运行。

1. 部署到 VPS

# On your VPS
git clone https://github.com/granitebps/youtube-mcp.git
cd youtube-mcp
npm ci
npm run build

# Create .env (optional, for HTTP mode)
cp .env.example .env
# Uncomment TRANSPORT=http, PORT, HOST as needed

YouTube 通常会屏蔽数据中心 IP。如果 get_video_info 返回 ACCESS_BLOCKED，并显示“请登录以确认你不是机器人”，请设置 YT_PROVIDER=api 和 YOUTUBE_API_KEY，通过官方 API 提供元数据、评论和搜索功能。请参阅提供商。

2. 使用 HTTP 传输运行

# Using --http flag
node dist/index.js --http

# Or using environment variable
TRANSPORT=http PORT=3000 node dist/index.js

# Or using npm script
npm run start:http

服务器将在 http://0.0.0.0:3000/mcp 上监听。

3. 使用 TLS 设置 Nginx 反向代理

server {
    listen 443 ssl;
    server_name mcp.yourdomain.com;

    ssl_certificate     /etc/letsencrypt/live/mcp.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mcp.yourdomain.com/privkey.pem;

    location /mcp {
        proxy_pass http://127.0.0.1:3000/mcp;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Required for SSE streaming
        proxy_set_header Connection '';
        proxy_buffering off;
        proxy_cache off;
        chunked_transfer_encoding on;
    }
}

获取免费的 TLS 证书：

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d mcp.yourdomain.com

4. 使用 systemd 保持运行

创建 /etc/systemd/system/youtube-mcp.service：

[Unit]
Description=YouTube MCP Server
After=network.target

[Service]
Type=simple
User=your_user
WorkingDirectory=/path/to/youtube-mcp
ExecStart=/usr/bin/node dist/index.js --http
Restart=always
RestartSec=5
Environment=TRANSPORT=http
Environment=PORT=3000
Environment=HOST=127.0.0.1

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable youtube-mcp
sudo systemctl start youtube-mcp
sudo systemctl status youtube-mcp

5. 将 MCP 客户端连接到 VPS

GitHub Copilot（VS Code）— 远程

{
  "mcp": {
    "servers": {
      "youtube": {
        "type": "http",
        "url": "https://mcp.yourdomain.com/mcp"
      }
    }
  }
}

Claude Desktop — 远程

{
  "mcpServers": {
    "youtube": {
      "type": "streamable-http",
      "url": "https://mcp.yourdomain.com/mcp"
    }
  }
}

---

使用示例

连接后，你可以向 AI Agent 提出如下请求：

• “获取此 YouTube 视频的信息：https://www.youtube.com/watch?v=dQw4w9WgXcQ”
• “显示视频 ID 为 abc123 的热门评论”
• “获取此视频的英文字幕”
• “总结 https://youtu.be/xyz789 的字幕”
• “搜索本周上传、按观看次数排序的 Node.js 教程”
• “查找上个月最受欢迎的 React 视频”

工具响应格式

所有工具都会返回：

• content：供聊天式 MCP 客户端使用的简短易读文本
• structuredContent：面向需要可靠字段的 Agent 的 JSON 格式数据

该服务器刻意采用 JSON 优先、文本其次 的设计。需要筛选、转换或串联工具结果时，Agent 应优先使用 structuredContent。

get_video_info 的示例结构：

{
  "content": [
    {
      "type": "text",
      "text": "📹 Example title\n\nChannel: Example channel\n..."
    }
  ],
  "structuredContent": {
    "videoId": "dQw4w9WgXcQ",
    "title": "Example title",
    "description": "Example description",
    "channelName": "Example channel",
    "channelId": "UC123",
    "uploadedAt": "Sep 14, 2017",
    "duration": "3m 33s",
    "durationSeconds": 213,
    "viewCount": "123456",
    "likeCount": "7890",
    "commentCount": null,
    "tags": ["music", "pop"],
    "thumbnailUrl": "https://..."
  }
}

YouTube 未提供的值为 null，绝不会使用 "0"、"N/A" 或 "Unknown" 等占位值。

错误

失败时会返回 isError: true。文本以代码开头（❌ [ACCESS_BLOCKED] ...），详细信息位于 _meta["youtube-mcp/error"] 中：

{
  "isError": true,
  "content": [{ "type": "text", "text": "❌ [ACCESS_BLOCKED] YouTube requires sign-in to access video C7OQHIpDlvA: Sign in to confirm you’re not a bot" }],
  "_meta": {
    "youtube-mcp/error": {
      "code": "ACCESS_BLOCKED",
      "message": "...",
      "retryable": false,
      "upstream": { "playabilityStatus": "LOGIN_REQUIRED", "reason": "Sign in to confirm you’re not a bot", "accessKind": "login_required" }
    }
  }
}

错误位于 _meta 中，而非 structuredContent，因为 MCP SDK 客户端会根据工具的输出架构验证所有 structuredContent，即使结果是错误也是如此。

代码	含义
INVALID_INPUT	不是 YouTube URL 或 11 个字符的视频 ID，或语言代码无效
ACCESS_BLOCKED	YouTube 拒绝了此客户端：HTTP 429/403、CAPTCHA、同意页面、登录要求或机器人检查。upstream.accessKind 的值为 rate_limited、forbidden、login_required、consent_required 或 quota_exceeded（官方 API 配额已用尽）。这并不说明视频是否存在或是否有字幕
VIDEO_UNAVAILABLE	YouTube 报告视频处于 ERROR、UNPLAYABLE 状态，或视频为私密或离线。upstream.reason 是 YouTube 提供的文本
CAPTIONS_UNAVAILABLE / LANGUAGE_UNAVAILABLE	内部使用；转录工具会将其作为 available: false 的结果返回，而不是错误
COMMENTS_UNAVAILABLE	评论已关闭，或 YouTube 未返回评论区
PARSE_ERROR	YouTube 已响应，但无法解析该响应（布局变更、返回了错误的视频 ID）
LIMIT_EXCEEDED	达到了已配置的大小限制
TIMEOUT	已超过配置的截止时间；底层请求已中止
CANCELLED	MCP 客户端取消了请求，或服务正在关闭
UPSTREAM_ERROR	其他 HTTP 或网络故障（retryable: true）

服务不会自行重试。

提供方

YT_PROVIDER 用于选择 get_video_info、get_video_comments 和 search_youtube 的后端。无论当前启用哪个提供方，get_video_transcript 和 get_transcript_languages 始终使用 youtube-transcript-plus。get_server_info 会报告当前启用的提供方。

提供方	通过以下方式选择	需要	说明
InnerTube	默认，或 YT_PROVIDER=innertube	无	通过 youtubei.js 使用非官方／内部接口，无需 Data API 密钥。YouTube 可能会限制或阻止访问，包括来自数据中心 IP（VPS、云服务）的访问
Official API	YT_PROVIDER=api	YOUTUBE_API_KEY	使用 YouTube Data API v3。受 Google Cloud 项目的配额、密钥限制和适用服务条款约束

此服务不使用 Data API 获取字幕。Google 的 字幕下载端点 要求通过 OAuth 授权，并且必须具有编辑视频的权限；仅有 API 密钥并不足够。转录工具使用非官方的 youtube-transcript-plus 路径，无论使用哪个提供方，都可能返回 ACCESS_BLOCKED。

使用官方 API

自带密钥（BYOK）。密钥归你所有；本项目不会分发或托管共享的 YouTube API 密钥。请通过进程或 MCP 客户端环境提供这些设置；服务不会自动加载 .env 文件。

1. 在 Google Cloud 控制台中创建项目，启用 YouTube Data API v3，并创建 API 密钥。建议将密钥限制为仅可用于该 API。
2. 使用以下命令启动服务：

YT_PROVIDER=api YOUTUBE_API_KEY=your_api_key npx -y @granitebps/youtube-mcp

配额（费用）：默认配额为每天 10,000 个单位，另有每天 100 次 search.list 调用的单独额度。

工具	API 调用
get_video_info	videos.list：1 个单位
get_video_comments	commentThreads.list：每页 1 个单位。page: N 会遍历此前的 N-1 页，因此需要 N 个单位
search_youtube	search.list（搜索额度）加一次用于获取观看次数和时长的 videos.list：1 个单位

结果会像默认提供方一样缓存（视频信息 30 分钟、评论 10 分钟、搜索 15 分钟），因此重复调用不会产生费用。配额用尽时，会返回 ACCESS_BLOCKED，并附带 upstream.accessKind: "quota_exceeded"；密钥无效或 API 未启用时，会返回 ACCESS_BLOCKED，并附带 accessKind: "forbidden"。

与默认提供方的区别：

• uploadedAt（get_video_info）和 publishedAt（评论、搜索）是 ISO 8601 时间戳，而不是 "Sep 14, 2017" 或 "2 days ago" 之类的显示文本
• 搜索结果中的 viewCount 是 "1234" 这类纯数字，而不是 "1.2K views"；duration 使用与 get_video_info 相同的格式（"3m 5s"）
• search_youtube 会精确应用所有 sortBy 和 uploadDate 值，并且不会返回 warnings。videoDuration: "short" 表示时长不足 4 分钟，medium 表示 4 到 20 分钟（YouTube API 的定义）
• get_video_comments 仅返回 API 随每个讨论串提供的回复（部分回复）；replyCount 是完整数量

配置

除 YT_PROVIDER=api 时的 YOUTUBE_API_KEY 外，所有设置都是可选的环境变量。无效值会导致服务在启动时停止，并在 stderr 输出消息。

变量	默认值	作用
YT_PROVIDER	innertube	视频信息、评论和搜索的提供方：innertube 或 api。请参阅提供方
YOUTUBE_API_KEY	无	你自己的 YouTube Data API v3 密钥。YT_PROVIDER=api 时必需，否则会忽略
YT_INIT_TIMEOUT_MS	15000	创建共享 YouTube 客户端的截止时间
YT_REQUEST_TIMEOUT_MS	20000	单次工具调用上游操作的截止时间，包括等待客户端初始化
YT_TRANSCRIPT_MAX_BYTES	5000000	每个字幕响应可读取的最大字节数
YT_TRANSCRIPT_MAX_SEGMENTS	50000	单条字幕轨道最多处理的字幕片段数
YT_TRANSCRIPT_PAGE_MAX_SEGMENTS	500	单次 get_video_transcript 响应最多返回的片段数

截止时间到期或客户端取消时，正在进行的 HTTP 请求会被中止，而不只是放弃等待。

工具详情

search_youtube

• 输入：query（搜索文本）、maxResults（1-50，默认值为 10）、sortBy（relevance | date | viewCount | rating）、uploadDate（any | hour | today | week | month | year）、videoDuration（any | short | medium | long）
• 返回：content 中的易读摘要，以及 structuredContent 中的结构化 JSON 结果
• 注意：使用默认的 innertube 提供方时，YouTube 搜索仅支持按相关性或热度排序，并且仅筛选从 today 起上传的内容。sortBy: "date" 保持相关性顺序，sortBy: "rating" 按热度排序，uploadDate: "hour" 会按 today 应用。每种情况都会在可选的 warnings 数组中添加一项（包含 code、message）。api 提供方会精确应用所有选项

get_video_info

• 输入：video（YouTube URL 或视频 ID）
• 返回：content 中的易读摘要，以及 structuredContent 中的结构化 JSON 元数据，包括 durationSeconds。只要 YouTube 提供视频详情，即使拒绝播放，也会返回元数据

get_video_comments

• 输入：video（URL 或 ID）、maxResults（1-20，默认值为 20）、sortBy（relevance 或 time）、page（默认值为 1）
• 返回：content 中的易读摘要，以及 structuredContent 中的结构化 JSON 评论串、分页字段和 hasMore
• 注意：replies 仅包含 YouTube 随评论串一并提供的回复；replyCount 是完整数量。获取其余回复需要为每个评论串单独发送一次请求

get_video_transcript

• 输入：video（URL 或 ID）、lang（可选语言代码；省略时使用第一条人工字幕轨道；若没有，则使用第一条自动生成字幕轨道）、maxSegments（默认值为 0：尽可能多地获取，最多不超过 YT_TRANSCRIPT_PAGE_MAX_SEGMENTS）、startSegment（默认值为 0）
• 返回：content 中的易读字幕文本，以及 structuredContent 中的结构化 JSON 字幕片段、纯文本和分页元数据。当 hasMore 为 true 时，使用 startSegment = nextStartSegment，并将返回的 languageCode 作为 lang 继续获取。isAutoGenerated 表示该字幕轨道是否为 YouTube 自动生成
• 无字幕：返回 available: false 和 reason: "NO_CAPTIONS"，或者返回 reason: "LANGUAGE_UNAVAILABLE" 及 availableLanguages。访问问题会作为错误返回，绝不会返回 available: false
• 注意：如果某种语言同时有人工字幕轨道和自动生成字幕轨道，则返回人工字幕轨道
• 注意：不需要 API 密钥——通过 YouTube 的内部字幕系统运行。字幕文本仅为字幕内容，不是对视频画面的分析

get_transcript_languages

• 输入：video（YouTube URL 或视频 ID）
• 返回：content 中的易读语言列表，以及 structuredContent 中的结构化 JSON 语言元数据。available: false 表示视频可以播放，但没有字幕轨道；访问问题会作为错误返回

get_server_info

• 输入：无
• 返回：name、version、provider（innertube 或 api）、authenticated、exactSearchFilters，以及 tools（从各工具映射到为其提供服务的后端）

开发

npm test        # builds, then runs the offline test suite (no network access)
npm run check   # tests plus release metadata, package contents, and tarball install checks

请参阅 CONTRIBUTING.md。

发布验证

自动化测试套件涵盖输入解析、配置、错误分类、取消操作、已编译的 stdio 入口、发布元数据，以及从 npm tarball 安装。测试不会调用 YouTube。YouTube 在线检查为手动执行，与 CI 分开进行。

维护者按照发布指南执行经批准的标签发布流程，包括 npm、MCP Registry 和 GitHub 发布。

速率限制

默认的 innertube 提供方和字幕工具使用非官方的 YouTube 接口。它们不使用 Data API 配额系统，但这并不意味着可以不受限制地访问：

• 大量自动化使用可能触发 CAPTCHA 或临时封锁
• 来自数据中心 IP（VPS、云）的请求通常会被直接封锁
• 控制请求频率并不能保证能够访问，也不能证明符合服务条款

api 提供方则受 Google Cloud 项目的 YouTube Data API 配额限制。请参阅提供方。

许可证

ISC。软件许可证与 YouTube/Google 服务条款及所获取内容的权利分开。请参阅访问指南。