YouTube MCP Server

一个托管的 Model Context Protocol (MCP) 服务器，为 Claude、Cursor、Windsurf 以及任何其他 MCP 客户端提供四个只读的 YouTube 工具。无需 Google Cloud 项目和 YouTube Data API 密钥，即可搜索 YouTube、读取视频和频道数据并获取转录文本。

https://mcp.hasdata.com/api/mcp?apis=youtube

目录

• 你需要什么

• 快速开始

• 示例提示

• 工具

• 错误与失败路径

• 定价、免费层级与限制

• 工具选择

• 对比

• 常见问题

• HasData 链接

• 开发

• 贡献

• 许可协议

Related MCP server: YouTube MCP Server

你需要什么

一个支持带自定义头的流式 HTTP 的 MCP 客户端。从仪表盘免费创建一个 HasData API 密钥。仅此而已。这是一个远程服务器，因此无需安装任何软件包、无需运行任何容器，整个流程中也不需要 Google 账户。

快速开始

服务器 URL 对所有客户端都相同。已使用以下配置在 Claude Code、Claude Desktop、Cursor、Windsurf 和 Cline 上完成测试。

支持 OAuth 的客户端可以将同一 URL 作为连接器添加并登录，这样密钥就不会出现在配置文件中。

claude mcp add --transport http youtube "https://mcp.hasdata.com/api/mcp?apis=youtube" \
  --header "x-api-key: your_key_here"

依次进入设置、连接器，然后添加自定义连接器，粘贴 https://mcp.hasdata.com/api/mcp?apis=youtube 并登录。

对于配置文件方式，请将其添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "youtube": {
      "type": "http",
      "url": "https://mcp.hasdata.com/api/mcp?apis=youtube",
      "headers": { "x-api-key": "your_key_here" }
    }
  }
}

~/.cursor/mcp.json 适用于所有项目，或 .cursor/mcp.json 仅适用于单个项目：

{
  "mcpServers": {
    "youtube": {
      "url": "https://mcp.hasdata.com/api/mcp?apis=youtube",
      "headers": { "x-api-key": "your_key_here" }
    }
  }
}

~/.codeium/windsurf/mcp_config.json。Windsurf 将该字段称为 serverUrl，而不是 url：

{
  "mcpServers": {
    "youtube": {
      "serverUrl": "https://mcp.hasdata.com/api/mcp?apis=youtube",
      "headers": { "x-api-key": "your_key_here" }
    }
  }
}

{
  "mcpServers": {
    "youtube": {
      "url": "https://mcp.hasdata.com/api/mcp?apis=youtube",
      "type": "streamableHttp",
      "headers": { "x-api-key": "your_key_here" },
      "disabled": false
    }
  }
}

工作区中的 .vscode/mcp.json：

{
  "servers": {
    "youtube": {
      "type": "http",
      "url": "https://mcp.hasdata.com/api/mcp?apis=youtube",
      "headers": { "x-api-key": "your_key_here" }
    }
  }
}

~/.codex/config.toml：

[mcp_servers.youtube]
url = "https://mcp.hasdata.com/api/mcp?apis=youtube"

[mcp_servers.youtube.headers]
"x-api-key" = "your_key_here"

~/.gemini/settings.json：

{
  "mcpServers": {
    "youtube": {
      "httpUrl": "https://mcp.hasdata.com/api/mcp?apis=youtube",
      "headers": { "x-api-key": "your_key_here" }
    }
  }
}

更多客户端教程请参见 HasData 集成页面。

示例提示

提示词，而非代码。粘贴其中一条，代理会自行选择工具。每条都标注了所需的调用次数，因为在 MCP 中，模型决定发起多少次调用，而每次成功调用消耗 10 个积分。

查找上个月关于 Model Context Protocol 的观看次数最多的十个视频，然后提取其中排名第一的视频的转录文本，并告诉我它对工具调用所做的三个论断。

两次调用，20 积分。

获取频道 @GoogleDevelopers。列出它发布的标签页，然后总结最近五个上传视频，并告诉我哪些主题重复出现。

两次调用，20 积分。读取一个尚未见过的标签页需要第二次调用，因为标签页列表包含在第一次响应中。

获取视频 id dQw4w9WgXcQ。获取其统计信息，然后检查它的相关视频中有哪些来自同一频道。

一次调用，10 积分。相关视频会随同一响应一起返回。

在 YouTube 上搜索“web scraping tutorial”，按上传日期排序，仅限四分钟以内的视频，并给出每个包含章节的结果的章节标题。

一次调用，10 积分。

如果该视频存在德语音频转录文本，请提取出来，并告诉我它支持哪些语言。

一次调用，10 积分。

搜索使用 YouTube 自己的筛选标记，因此代理无需后处理即可按时长、上传日期和内容类型进行筛选。转录文本会附带可用语言轨道的列表，因此代理无需猜测即可选择。

分页每次都会消耗一次调用。一个研究型提示词如果搜索一次、翻页两次，然后再提取三个转录文本，那就是六次调用、60 积分。因此，试用额度在回答范围明确的问题时，比在开放式抓取中更耐用。

工具

四个工具，全部只读。下面的示例来自真实调用并经过删减，其中的数字会随 YouTube 的更新而变化，因此请将其视为示意结构。

获取 YouTube 搜索结果

hasdata_youtube_search_getYoutubeSearchResults

搜索 YouTube，并返回整个结果页，按结果类型拆分。

结果页被拆分为 videoResults、shortsResults、inlineShortsResults、playlistResults、channelResults 和 shelves，付费展示位位于 adsResults 和 sponsoredResults 中。出现哪些块取决于查询，而没有任何可报告内容的块是缺失的，而不是空的，因此在迭代之前要先测试键是否存在。searchInformation 携带总数，pagination.nextPageToken 就是你要作为 paginationToken 传回的内容。广告永远不会混入自然结果数组中，尽管有两个广告数组需要跳过。

{
  "positionOnPage": 1,
  "videoId": "GuTcle5edjk",
  "title": "you need to learn MCP RIGHT NOW!! (Model Context Protocol)",
  "viewsOriginal": "1.6M views",
  "views": 1653824,
  "length": "38:40",
  "publishedDate": "11 months ago",
  "extensions": ["4K"],
  "chapters": [
    { "title": "Intro", "time": "0:00" },
    { "title": "Problem: LLMs Suck at Accessing Code", "time": "0:40" }
  ],
  "channel": { "name": "NetworkChuck", "verified": true }
}

这里有两件事值得一提。views 是与 1.6M views 显示字符串并列的解析后整数，因此这里不需要后缀解析器。而且 chapters 会出现在搜索结果中，而不仅仅在视频本身，不过只有部分视频会携带它们。

搜索端点参考 列出了该端点接受的所有 sp 和 filters__ 标记。

获取 YouTube 视频数据

hasdata_youtube_video_getYoutubeVideo

按 ID 获取单个视频。

返回 title、thumbnail、channel、publishedDate、lengthSeconds、category、isFamilySafe 和 isUnlisted，以及 relatedVideos、endScreenVideos、keywords、captions、music 和 socialLinks 数组。description 是一个对象，其完整文本保存在 content 中，并带有一个 links 数组，其中每个链接和话题标签都携带 startIndex、length、text 和 url。text 字段保存作者书写的链接原文，url 保存 YouTube 的跳转包装，这在你从描述中提取赞助商或联盟营销目的地时很重要。

在复制下面的示例之前，请先按名称阅读每个工具的解析字段。搜索和频道结果将解析后的数字放在 views 中，将显示字符串放在 viewsOriginal 中。此响应则相反，将字符串保留在 views 中，将数字放在 extractedViews 中，likes 和 subscribers 也采用同样的反转。如果搞错了，item.views > 100000 在这里会比较字符串，而且永远不会抛出异常。

{
  "title": "Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)",
  "views": "1,806,075,152 views",
  "extractedViews": 1806075152,
  "likes": "19M",
  "extractedLikes": 19344370,
  "publishedDate": "Oct 24, 2009",
  "lengthSeconds": 214,
  "category": "Music",
  "channel": { "name": "Rick Astley", "subscribers": "4.53M subscribers", "extractedSubscribers": 4530000 }
}

完整字段列表请参见视频端点参考。

获取 YouTube 频道数据

hasdata_youtube_channel_getYoutubeChannel

按 ID 或用户名获取频道，一次一个标签页。

默认标签页返回 channelInfo、featuredVideo 和 sections。其他标签页返回各自的结构。channelInfo 包含句柄、头像、横幅、描述、频道关键词以及频道的 rssUrl，足以在不轮询频道的情况下持续关注。

下方示例中的 availableTabs 数组存放的是显示标签，并非 tab 参数可接受的值。Home、Live、Courses 和 Search 不对应任何参数值，其余的需要转成小写。如果智能体读取该列表并逐项遍历，会在第一项就失败。

{
  "channelInfo": {
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "name": "Google for Developers",
    "handle": "@GoogleDevelopers",
    "rssUrl": "https://www.youtube.com/feeds/videos.xml?channel_id=UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "isFamilySafe": true,
    "availableTabs": ["Home", "Videos", "Shorts", "Live", "Courses", "Playlists", "Posts", "Search"]
  }
}

每个标签页及其结构详见频道端点参考。

获取 YouTube 视频字幕

hasdata_youtube_transcript_getYoutubeTranscript

视频的带时间轴字幕。

在信任语言之前，请先检查响应中的 selected。请求视频不包含的 languageCode 既不会失败也不会返回空结果，而是会静默回退到默认音轨。列表中的每个条目都带有 languageName 和 languageCode，同一种语言可能出现两次，一次是人工编写的，另一次 type 设置为 asr。

{
  "transcript": [
    { "startMs": 320, "endMs": 18800, "snippet": "[Music]", "startTimeText": "0:00" },
    { "startMs": 18800, "endMs": 21800, "snippet": "We're no strangers to", "startTimeText": "0:18" }
  ],
  "availableTranscripts": [
    { "languageName": "English", "languageCode": "en" },
    { "languageName": "English", "languageCode": "en", "type": "asr", "selected": true },
    { "languageName": "German (Germany)", "languageCode": "de-DE" },
    { "languageName": "Japanese", "languageCode": "ja" }
  ]
}

语言代码和 asr 标志详见字幕端点参考。

错误与失败路径

你的客户端几乎不会从工具调用中看到 HTTP 错误码。MCP 层返回 200，并将失败信息放在结果中，isError 设置为 true，原因以文本形式给出，因此智能体读到的是消息，而不是你可能预期的状态行。

错误的密钥会以工具输出的形式出现，而不是连接失败。 tools/list 接受任何非空密钥并返回全部四个工具，因此客户端完成握手并显示绿色。第一次工具调用随后返回 isError: true 和文本 HasData API error: 401 Unauthorized。请留意这个字符串，因为流程中之前没有任何地方报告该问题。

缺少密钥是唯一真正的 HTTP 错误。 授权在任何工具之前执行，因此连接本身会以 401 失败。CORS 头存在，浏览器客户端读取的是状态码，而不是不透明的网络错误。

破坏工具 schema 的参数永远不会离开你的客户端。 它会以 MCP error -32602: Input validation error 失败，并指明违规字段。该调用永远不会到达 HasData，也不会产生任何费用。消息会指明字段名，但不会列出可接受的值，因此上面的参数表就是参考依据。

调用成功但未找到任何内容是最容易让人困惑的情况。 它作为普通结果返回，requestMetadata.status 为 ok，而数据键直接缺失。响应体中没有任何内容表明结果为空。请测试你需要的字段，而不是测试错误。

平台拒绝的标识符返回 400，requestMetadata.status 设置为 error。不存在的频道句柄是常见的触发方式。

携带数据的结果还带有 requestMetadata.id，在联系支持时值得引用。

定价、免费额度与限制

每个 YouTube 工具每次成功调用消耗 10 个积分。响应大小不会改变价格，因此一整页搜索结果与只有一条视频的页面价格相同。

免费试用为30 天内 1,000 个积分，无需绑定银行卡，即 100 次 YouTube 调用。之后，活跃账户在余额低于 100 时每天自动补充 100 个积分，因此低流量智能体可以无限期地在免费层运行。

付费套餐起价为每月 $49，包含 200,000 个积分，即 20,000 次调用。单价随用量下降，从入门套餐的每 1,000 次调用 $2.45 降至 Business 的 $0.99、Growth 的 $0.83，以及最大高流量套餐的 $0.75。最新数字见定价页面。

你的套餐还决定并发数。免费试用允许同时 1 个请求，Startup 为 15，Business 为 30，Growth 为 50，高流量套餐为 200 到 1,500。在任何无人值守的场景中都要防御性地处理溢出情况，因为扇出的智能体会比你更早触达上限。

返回非 200 的请求不收费。成功调用但未找到任何内容仍然算一次调用。

工具选择

apis 查询参数决定你的智能体能看到哪些工具。工具越少，用于工具定义的上下文就越少，模型选错工具的机会也越少。

?apis=youtube                    the four tools in this repo
?apis=youtube,google_serp        add Google search
?apis=youtube,tiktok,instagram   a social research bundle

该参数接受 youtube 这样的提供商名称，也接受 google_maps_search 这样的单个 API 名称。拼写错误的名称会被忽略。如果所有名称都错误，请求会以 400 失败，响应体会列出无法识别的名称以及所有有效值。去掉该参数后，同一端点会暴露全部 57 个 HasData 工具。

对比

与官方 YouTube Data API v3 相比：

最后两行很重要。如果每日配额足以覆盖你的用量，并且你查询的是自己拥有的频道，那么官方 API 是更便宜的选择，你应该采用它。

大多数其他 YouTube MCP 服务器只提供字幕功能。本服务器还能搜索、读取带互动数据的视频，并遍历频道标签页，因此智能体无需第二个服务器即可完成整个研究流程。

本服务器不做什么。 不支持评论、频道管理、上传、分析或私有数据。它只读取未登录访客能看到的内容。

常见问题

有官方的 YouTube MCP 服务器吗？

Google 没有发布。YouTube 没有第一方 MCP 服务器，因此所有选项都是其他人构建的，要么基于 YouTube Data API v3，要么基于公开页面。本服务器由 HasData 维护，读取公开页面，因此不需要 Google 凭据。

什么是 YouTube MCP 服务器？

一种将 YouTube 数据以 AI 客户端可调用的工具形式暴露出来的服务器。客户端通过 Model Context Protocol 发送工具调用，服务器获取数据并返回结构化 JSON，模型处理结果而永远不会看到 HTML 页面。本服务器暴露四个工具并远程运行，因此客户端连接到一个 URL，无需启动任何本地进程。

我需要 YouTube API 密钥或 Google Cloud 项目吗？

不需要。唯一的凭据是你的 HasData 密钥。无需创建 Google Cloud 项目、填写配额表单或面对 OAuth 同意屏幕，因为这些工具读取的是 YouTube 公开页面，而不是 YouTube Data API。

我需要托管或运行任何东西吗？

不需要。这是一个基于 streamable HTTP 的远程 MCP 服务器。无需安装任何东西，无需保持容器运行，无需重启进程。

数据是实时的还是缓存的？

实时的。每次调用都会在请求时获取页面，并带有自己的 requestMetadata.id，因此两次相同的调用是两次独立的获取，而不是重放存储的副本。观看次数和点赞数等计数器跟随页面变化，因此它们会随页面一起变动。

YouTube 更改布局时会发生什么？

你这边什么都不用做。我们会跟踪变更并保持响应 schema 稳定，因此字段名和类型保持不变。没有值的字段会从条目中缺失，而不是存在但为 null，因此请使用默认值读取可选字段。

我可以将它与其它 HasData API 一起使用吗？

可以。apis 参数接受列表，因此 ?apis=youtube,google_serp 会为你的智能体提供四个 YouTube 工具以及 Google 搜索。去掉该参数即可获得全部工具。参见工具选择。

我可以获取任何视频的字幕吗？

只有在视频有字幕的情况下，availableTranscripts 会在你询问之前告诉你存在哪些内容。

我可以使用 OAuth 登录而不是粘贴密钥吗？

可以，在支持此功能的客户端中可以。Claude Desktop 和 Cursor 可以将该端点添加为连接器并登录。无人值守的代理和脚本使用 x-api-key 请求头。

合规性与个人数据

HasData 仅访问公开可用的数据。平台的条款可能限制自动访问，您需要自行负责合规性。如果您收集的数据包含个人信息，请确保您根据 GDPR、CCPA 或您所在司法管辖区的等效规则拥有合法的处理依据。

HasData 链接

开发

此仓库是远程服务器的配置和文档，因此没有构建步骤，也无需容器化。

test/ 中的测试断言工具契约，即无需在此提交即可失效的部分。它们检查 ?apis=youtube 是否恰好返回四个工具，每个工具是否仍声明其必需参数，名称是否未更改，以及正在使用的密钥是否确实被接受。最后一项检查会真实调用一个工具并消耗 10 个积分，这相当于养一只金丝雀的代价，它可能因为正确的原因而失败。

# macOS and Linux
HASDATA_API_KEY=your_key_here npm test

# Windows PowerShell
$env:HASDATA_API_KEY="your_key_here"; npm test

同一套测试套件会在每次推送时以及每周定时在 CI 中运行，因为上游工具列表可能会在无人修改此仓库的情况下发生变化。失败意味着工具列表已变动、密钥已失效或端点无法访问，断言消息会说明具体是哪种情况。

贡献

对工具表和响应示例的更正是最有用的贡献，因为这些部分容易发生漂移。请附上您发出的调用和收到的响应。来自 fork 的拉取请求会在没有密钥的情况下运行测试套件，因此实时检查会跳过，不会出现红色失败。

许可证

MIT。请参阅 LICENSE。