YouTube MCP Server

YouTube MCP Server

一个托管的 Model Context Protocol（MCP）服务，为 Claude、Cursor、Windsurf 和其他任何 MCP 客户端提供四种只读 YouTube 工具。搜索 YouTube、读取视频和频道数据，以及提取字幕，无需 Google Cloud 项目或 YouTube Data API 密钥。

每月 1,000 个免费额度，无需绑定银行卡，可调用 YouTube 100 次。

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

• 提示词和资源

目录

• 所需条件
• 快速开始
• 提示词示例
• 工具
• 错误和失败处理路径
• 定价、免费套餐和限制
• 工具选择
• 对比
• 常见问题
• HasData 链接
• 开发
• 贡献
• 许可证

所需条件

一个支持带自定义标头的可流式 HTTP 的 MCP 客户端。一个从控制面板获取的 HasData API 密钥，创建密钥免费。无需其他条件。这是一个远程服务，因此最简单的接入方式是使用 URL 和标头，无需运行容器，整个流程也不需要 Google 账号。仅支持 stdio 的客户端可以改用 @hasdata/youtube-mcp（npm）或 hasdata-youtube-mcp（PyPI）启动器。

快速开始

所有客户端使用相同的服务器 URL。我们会在 Claude Code 和 Claude Desktop 中手动运行。其他代码块则遵循各客户端为远程服务规定的格式。

支持 OAuth 的客户端可以将相同的 URL 添加为连接器，然后登录，无需将密钥放入配置文件。

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

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "@hasdata/youtube-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}

{
  "mcpServers": {
    "youtube": {
      "command": "uvx",
      "args": ["hasdata-youtube-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}

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

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

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

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

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

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

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

提示词示例

这些是提示词，不是代码。粘贴一条，Agent 就会自行选择工具。每条都注明了所需调用次数，因为在 MCP 中，由模型决定调用几次，每次成功调用都会消耗 10 个积分。

找出过去一个月关于 Model Context Protocol 的观看次数最多的 10 个视频，然后提取排名第一的视频字幕，并列出其中关于工具调用的 3 个论点。

调用两次，消耗 20 个积分。

查看频道 @GoogleDevelopers。列出该频道发布的各个标签页，然后总结最近上传的 5 个视频，并指出重复出现的主题。

调用两次，消耗 20 个积分。读取尚未查看过的标签页需要额外调用一次，因为标签页列表会包含在第一次响应中。

查看这个视频 ID：dQw4w9WgXcQ。获取其统计数据，然后检查相关视频中哪些来自同一频道。

调用一次，消耗 10 个积分。相关视频会一并包含在同一个响应中。

在 YouTube 上搜索“web scraping tutorial”，按上传日期排序，只看时长少于 4 分钟的视频，并列出每个有章节的视频的章节标题。

调用一次，消耗 10 个积分。

提取这个视频的德语字幕（如果有），并告诉我该视频提供哪些语言版本。

调用一次，消耗 10 个积分。

搜索会使用 YouTube 自己的筛选标记，Agent 无需后处理即可按时长、上传日期和内容类型缩小范围。字幕会与可用语言轨道列表一并返回，因此 Agent 可以直接选择一种语言，无需猜测。

每次翻页都需要一次调用。一个先搜索、翻两页、再提取 3 份字幕的研究提示词需要调用 6 次，消耗 60 个积分。相比开放式爬取，免费套餐更适合回答范围明确的问题。

工具

这 4 个工具均为只读。以下示例摘自真实调用，但其中的数字会随着 YouTube 更新而变化。请将它们视为数据结构示例。每个工具名称都链接到对应的端点参考文档，其中包含完整的字段列表。

这些示例展示的是负载，而不是完整响应。tools/call 结果包含一个文本块，该文本本身是一个包含 url、status、text 和 json 的 JSON 对象，抓取的数据位于 json 下。从原始 JSON-RPC 响应中读取时，路径为 result.content[0].text，解析后再访问 .json。聊天客户端会为你解包，而直接与端点通信的代码不会。

获取 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 都不对应任何参数值；其余值则需要转换为小写。读取此列表并逐项遍历的 Agent 会在第一项就失败。

{
  "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" }
  ]
}

提示词和资源

该服务提供 2 个提示词，即客户端可以直接提供给用户的现成工作流，无需用户自行编写工具调用。

此外，该服务还公开 10 个资源，每个资源对应一个取值范围为固定列表的参数。读取资源比因调用被拒而学习相关词汇更省力，而且不消耗额度。每个 URI 的格式为 hasdata://youtube/<parameter>。

这两类列表均可在无需 API 密钥的情况下获取，因此客户端可以在用户注册前读取它们。

错误和失败路径

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

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

缺少密钥是唯一真正的 HTTP 错误。 授权会在任何工具执行前进行，连接本身会以 401 失败。响应中包含 CORS 标头，浏览器客户端可以读取状态，而不是只能收到不透明的网络错误。

不符合工具架构的参数会在触发抓取前被拒绝。 服务会返回 isError: true，文本为 MCP error -32602: Input validation error，并指出有问题的字段。不会抓取任何内容，也不会产生费用。消息会指出字段，但不会列出可接受的值，因此请参阅上方的参数表。

调用成功但没有找到任何内容，是最容易让人困惑的情况。 它会作为普通结果返回，其中 requestMetadata.status 设为 ok，而数据键则直接缺失。正文中没有任何内容会说明结果为空。请检查所需字段，而不是检查是否出错。

平台不接受的标识符会返回 400，且 requestMetadata.status 设为 error。不存在的频道句柄是最常见的触发方式。

包含数据的结果也会带有 requestMetadata.id，联系支持时值得引用该 ID。

定价、免费套餐和限额

每次成功调用 YouTube 工具都会消耗 10 个点数。响应大小不会影响价格。一整页搜索结果和仅含一个视频的页面价格相同。

免费套餐每月提供 1,000 个点数，无需绑定银行卡，可调用 YouTube 工具 100 次。套餐会随计费周期续订，因此低调用量的 Agent 可以无限期使用免费套餐。

付费套餐起价为每月 $59，包含 200,000 个点数，可调用 20,000 次。用量越大，单价越低：入门套餐为每 1,000 次调用 $2.95，Basic 为 $1.19，Growth 各档为 $0.83。最新价格请查看定价页面。

套餐还决定并发数。免费套餐允许同时发起 1 个请求，Startup 为 5 个，Basic 为 15 个，Growth 各档则为 50 到 500 个。在任何无人值守的任务中，都应妥善处理超出限额的情况，因为并行发起大量请求的 Agent 会比你更早触及上限。

返回非 200 的请求不会计费。成功调用但没有找到任何内容，仍会计为一次调用。

工具选择

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

?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 服务只提供字幕。此服务还可搜索、读取带有互动数据的视频，以及浏览频道标签页，因此 Agent 无需连接第二个服务即可完成整个研究流程。

此服务不提供的功能。 不支持评论、频道管理、上传、分析数据或私人数据。它读取的是未登录访客能够看到的内容。

常见问题

有官方的 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 密钥。由于这些工具读取的是 YouTube 公开页面，而不是 YouTube Data API，因此你无需创建 Google Cloud 项目、填写配额申请表或配置 OAuth 同意屏幕。

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

不需要。这是一个基于可流式传输 HTTP 的远程 MCP 服务。无需安装任何内容，也无需保持容器运行或重启进程。

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

数据是实时的。每次调用都会在请求时获取页面，并附带自己的 requestMetadata.id。两次相同的调用会分别获取数据，不会重放已存储的副本。观看次数和点赞数等计数会随页面变化而更新。

YouTube 更改版式后会怎样？

你无需做任何处理。我们会跟踪这些变化并保持响应架构稳定，因此字段名称和类型不会改变。没有值的字段不会出现在条目中，而不是以 null 值呈现。读取可选字段时，请设置默认值。

我可以将此服务与其他 HasData API 一起使用吗？

可以。apis 参数接受一个列表；使用 ?apis=youtube,google_serp，Agent 就能获得四种 YouTube 工具以及 Google 搜索工具。移除该参数，即可获得所有工具。

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

仅当视频提供字幕时才可以；你可以先查看 availableTranscripts，了解有哪些字幕可用。

我可以通过 OAuth 登录，而不是粘贴密钥吗？

可以，但需要客户端支持。Claude Desktop 和 Cursor 可以将该端点添加为连接器并登录。无人值守的 Agent 和脚本则使用 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。