tubelab-mcp

TubeLab MCP：数据层

TubeLab 是一个只读的公开 YouTube 数据索引。它保存表现突出的频道、异常值视频和热门标题公式，每日刷新；还可实时读取频道、视频、字幕稿和评论。此技能不是工作流。它记录了我们运行工作流技能时总结出的内容：成本、创作规则和注意事项。工具调用失败或没有返回结果时，或者不确定该使用哪个工具或筛选条件时，请打开此技能。

此处不再重复完整的参数和 REST 参考。请参阅文末的“完整参考”。

连接与检查

• MCP 端点为 https://public-api.tubelab.net/mcp。大多数客户端通过 OAuth 连接。Cursor 和其他 IDE Agent 会将 API 密钥作为 Authorization: Bearer <key> 发送，这需要 Pro 或 Team 计划。各客户端的设置说明：https://tubelab.net/docs/api/mcp-server
• 不确定时，先调用 get_credits_balance。此操作免费。
• Starter 计划包含 MCP。Starter 账户中的变现、收入、RPM 和受众字段可能为空。计划：https://tubelab.net/pricing

工具一览

MCP 工具名称与 REST 路径不同，工具架构也不会显示费用。

工具	费用	用途
search_channels	5 个积分	按主题搜索频道，支持许多筛选条件。用于寻找细分领域的工具。
search_related_channels	5 个积分	搜索与一个或多个频道 ID 相似的频道。用于建立竞争对手列表。
search_outliers	2 个积分	搜索表现超过自身频道平均水平的视频。了解当前哪些内容有效。
search_related_outliers	2 个积分	搜索与某个标题、视频、缩略图（按图像使用 thumbnailVideoId）或某个频道的视频（使用 relatedChannelId）相似的异常值视频。
search_trending_formats	1 个积分	搜索标题公式及其使用统计和示例视频。仅支持英语。不要传入 language。
get_channel、get_channel_videos	免费	返回相同的数据：频道统计信息，以及最多 120 个按时间倒序排列并带有异常值标记的长视频。调用一次即可。
get_channel_shorts	免费	返回带有异常值标记的 Shorts 样本。
get_video	免费	标题、说明、标签、发布日期、观看次数、点赞数和评论数。
get_video_transcript	免费	字幕稿文本及带时间信息的 events[]。
get_video_comments	免费	最多 100 条热门评论。
get_credits_balance	免费	剩余积分。

无论 size 是多少，每次调用的费用都相同。在短时间窗口内重复相同请求不会再次收费。更改一个筛选条件即视为新请求，需要再次付费。

标识符与链接

• 频道工具接受频道 ID（UC...）、URL 或句柄（@name）。如果搜索结果中已有 ID，请优先使用 ID。
• 视频工具需要不带其他内容的 11 位视频 ID。从 watch?v=ID、youtu.be/ID、shorts/ID 或 embed/ID 中提取，并去掉 &t= 和其他参数。
• 搜索结果包含 id（视频）和 snippet.channelId。请使用这些值。切勿猜测 ID。
• 仅使用工具返回的数据构建报告链接。视频：https://www.youtube.com/watch?v=<id>。片段：在相同链接后加上 &t=<seconds>s，其中秒数为 startMs 除以 1000。频道：https://www.youtube.com/@<handle>；没有句柄时使用 https://www.youtube.com/channel/<channelId>。品牌、产品和优惠：使用说明中读取到的 URL；如果它们只在视频中被提及，则使用对应的视频片段。

撰写规则

1. 先宽后窄。 先进行一次宽泛搜索，并阅读返回结果。然后再添加筛选条件。首次调用就设置 6 个筛选条件往往会一无所获，成本却相同。
2. 优先考虑时效性。 始终使用一个令牌设置 publishedAtFrom：month、trimester、semester 或 year，不要使用日期。如果结果太少，就一次放宽一个级别，并在报告中说明。
3. 始终启用 Content Authenticity。 classificationQuality: "neutral" 表示 General 及以上，因为服务会纳入 positive。对于小众、异常值、创意和标题相关工作，使用 neutral。对于任何与缩略图有关的内容，使用 positive（High）。切勿为了扩大稀少的结果集而降低此项设置。应放宽时效性，或移除其他筛选条件。negative 仅用于审核低质量内容。niche-watchlist 是例外：其已保存的搜索会省略此筛选条件。
4. 关注比率，而非原始观看量。 averageViewsRatio 是观看量除以频道平均观看量。它和 zScore 可说明某种形式是否奏效。原始观看量只能说明频道规模较大。按比率排序，同时展示两者，并在每个比率旁标注频道订阅者数量。
5. 默认使用语义搜索。 by: "semantic" 可理解主题。by: "lexical" 匹配确切词语。query 接受同一主题的 1 至 3 种表述，而不是主题列表。
6. 稳定分页。 使用 from 分页，它是从 0 开始的结果偏移量，因此第 2 页为 from: size。同一次搜索的每一页都使用相同的 seed 和筛选条件。不设置 sortBy 时，结果会按带种子的随机顺序排列，这也是应用首次加载时显示结果的方式。每一页都会产生新的费用。除非用户提出要求或技能说明如此，否则最多获取两页。niche-finder 会将其两次频道搜索各分页到 3 至 4 页。
7. 排除低质量小众内容。 在频道搜索中将质量下限与 excludeNiche 配合使用，在异常值搜索中与 excludeKeyword 配合使用。从此列表开始，删去属于用户小众领域的内容，并添加用户自己的排除项：music, song, lofi, movies, trailer, compilation, kids, nursery, news, politics, lingerie, haul, asmr, reaction, live stream。
8. 估算只是估算。 收入、RPM 和受众字段都是模型输出。用它们对结果排序，并以区间形式展示。切勿将它们作为事实引用，也不要据此筛选，除非用户提出要求。
9. 信号稀少时。 命中少于 5 条，不足以构成趋势。应如实说明并放宽一次。如果仍然稀少，就报告“无信号”，不要凭空编造。
10. 证据行。 每项关于频道或视频的陈述都应附上：频道（账号名） · 视频标题原文 · 观看量 · 比率 · 发布日期。所有引用内容都要附上工具数据中的 URL。仅听到的赞助商信息，应链接到视频中提及该赞助商的片段。对估算内容加以标注。如果没有获取相关信息，就不能声称知道。

解读结果

• 如何判断频道搜索结果是否可信。 按 semantic.niches[] 对频道进行聚类。中位观看次数反映需求；平均值会被异常值拉高。观看次数与订阅者数之比高于 1，说明算法会向订阅者以外的用户展示该频道。变异系数低于 1，说明观看次数稳定；高于 1.5，则说明该频道的表现靠少数热门视频支撑。无法按异常值数量筛选，因此请查看每条结果上的 positiveOutliersCount。
• 区分索引值与实时读取值。 搜索结果的统计数据来自索引。get_channel 读取的是实时数据。对于规模较小或较新的频道，两者可能相差很大。读取频道时，请使用实时值并说明使用的是哪个值。
• 应用默认视图。 Niche Finder 默认使用 subscribersFrom: 1、medianViewsFrom: 1000、videosCountFrom: 2，且不排序。Outliers Finder 默认使用 viewCountFrom: 5000、type: "video"，且不排序。使用这些设置，才能获得与用户在应用中看到的相同、无偏样本。
• 频道日期。 joinedDateFrom 表示频道的创建时间。sortBy: "foundAt" 按 TubeLab 首次发现频道的时间排序。
• 无露脸标记是预测结果。必要时请通过缩略图核实。
• 赞助商。 公共 API 会移除 monetization 中的 sponsored 标记。请改为读取 detections.sponsored.detected。
• 发达地区受众。 RPM 估算对这些地区最可靠。请按 audienceRegion 021（北美）、154（北欧）、155（西欧）和 053（澳大利亚与新西兰）筛选，并将收入设为 upper_middle 或 high。优先使用此方法，而不是按 RPM 筛选。
• Shorts。 对 Shorts 频道，请将 contentKind: "short-form" 与 filterBy: "short" 配对使用，这样范围筛选才会读取 Shorts 统计数据。对于仅有 Shorts 的频道，变现数据准确度较低。
• 热门内容形式。 framework 是带有 [X] 占位符的模板。pattern 是传给 search_outliers 的 titlePattern 值，不作任何修改。overall_stats.doc_count 是采用该形式的视频数量。结果不包含热度变化数据；热度变化只用作排序依据。因此，“上升”只能表示“出现在按热度变化排序的列表中”。
• Niche Analyzer 评分。 应用会对某个细分领域的频道样本评分，范围为 0 到 100，每项最高为 100。请排除订阅者少于 1,000 的频道，因为它们的比率毫无意义。市场规模为每个频道观看次数最多的视频的平均值 ÷ 1,000,000 × 100。未饱和度为 (平均观看次数 ÷ 订阅者数) ÷ 1.1 × 100 的平均值。盈利能力为 RPM 预估低值 ÷ 7 × 100 的平均值。低于 50 表示较弱，50 到 70 表示尚可，71 及以上表示较强。
• 缩略图。 视频结果包含 thumbnails.high.url；频道结果中的该字段则是头像。任何视频 ID 也可用于 https://i.ytimg.com/vi/<id>/hqdefault.jpg。在报告中，请展示 320 像素的 https://i.ytimg.com/vi/<id>/mqdefault.jpg。所有视频都有此缩略图，而且能让报告保持简洁；maxresdefault.jpg 曾返回 404。工具返回的是链接，而非图片，因此请务必下载并打开所分析的每个视频的缩略图。如果确实无法获取图片，请说明未查看，绝不要描述未看过的图片。
• 转录文本。 一段 30 分钟的视频会返回超过 100KB 的内容。如需查看开场，请读取 events[]，直到 startMs 超过 45000，然后停止。转录文本保留口语所用的语言。
• 大型响应。 频道读取结果和转录文本可能长达 75K 个字符或更多。请提取所需内容，绝不要原样复述。有些客户端会将超大响应保存到以时间戳命名的文件中，而并行触发的读取可能会互相覆盖对方的文件。请一次获取一个大型读取结果，并解析保存的文件。

特殊情况和错误

• search_trending_formats 会因 language 报错："Expected string, received array"。MCP 架构将每个搜索工具的 language 列为数组，但此后端需要字符串。请省略此参数；默认值为英语。
• 省略参数时，search_trending_formats 默认使用英语、quality: "positive"、videosCountFrom: 18，按 lastVideosCountChangePercentage 排序，size: 12，并使用过去 4 个月内发现的公式。
• search_related_channels 按相似度而非规模排序。使用大型种子频道时，返回的会是规模较小的相似频道，除非添加 subscribersFrom。
• 在 search_outliers 中设置较高的 viewCountFrom 下限，会出现播放量比率达到 50 及以上的付费品牌推广活动。请添加 channelMonetizationAdsense: true，或手动移除这些结果。
• 使用 title 锚点的 search_related_outliers 曾返回不相关的结果，并忽略 publishedAtFrom 和 classificationQuality。videoId、thumbnailVideoId 和 relatedChannelId 锚点表现正常。search_outliers 使用 by: "lexical" 时曾忽略查询。在这两种情况下，继续投入前，请确认结果与主题相关。
• 异常视频搜索中的 language 匹配的是已编入索引的标题语言，而非音频语言。标记为英语的标题可能对应印地语、乌尔都语或泰米尔语视频。标题文字和缩略图文字通常能揭示实际语言。必要时，请通过 get_video 检查 defaultAudioLanguage。
• channelVideoCountTo 的上限为 120，因为频道会采样 120 个视频。titlePattern 必须包含 * 和至少两个字母。每个范围都必须同时设置 from 和 to。
• 频道样本日期（publishedAtEstimate）和评论日期的精度仅到月份。评论点赞数通常为 null。
• 评论被禁用时，get_video_comments 会返回 "Failed Dependency" 或 "No comments found"。请将其视为没有数据，而非失败。其 comments[] 可能包含重复条目，因此请按作者和文本去重。即使是创作者置顶的评论，authorIsChannelOwner 在每一行中也都曾返回 null。请将作者账号名与频道账号名匹配，以识别创作者的回复。
• hits 为空且 pagination.total: 0 时：扩大时间范围、移除一个筛选条件或改写 query。保留质量下限。
• pagination.total 曾恰好返回 size 的两倍。请勿用它衡量细分领域的竞争程度。
• get_channel 不包含受众、变现、收入或 RPM 字段。这些字段只会出现在搜索结果中，而且搜索结果中可能不会出现被搜索的频道本身。
• HTTP 429 表示触发速率限制，MCP 每个时间窗口约允许 30 次调用，所有会话共享此限制。请等待限制重置后重试。读取操作请分散进行，不要一次性全部发出。

消耗额度

使用付费搜索来发现候选项，使用免费读取来了解候选项。每项工作进行 2 到 6 次搜索是合理的，付费搜索不会在循环中翻页。一个技能会深入探索，因为样本就是产品：niche-finder 会将两个频道搜索各翻 2 到 4 页。如果搜索报错，请调用 get_credits_balance，然后减少筛选条件重试一次。请勿在报告中提及预算和额度；用户询问时再提供。

完整参考

• 连接到 MCP 后，工具架构会列出所有参数名称和允许的值。猜测筛选条件前请先阅读。
• 如需查看完整参数列表、响应结构、REST 端点、身份验证、分页和错误代码，请获取 https://tubelab.net/docs/skill.md。该文档由 API 规范生成，因此会保持最新。
• 需要架构未说明的参数、通过 REST 而非 MCP 操作，或用户询问 API 工作方式时，请获取该文档。使用 REST 时，参数名称相同，频道端点接受的是频道 ID，而非账号名。