tubelab-mcp

TubeLab MCP：データレイヤー

TubeLab は、公開されている YouTube データの読み取り専用インデックスです。急成長中のチャンネル、突出した動画、トレンドのタイトルの定型を保持し、毎日更新しています。また、チャンネル、動画、文字起こし、コメントをリアルタイムで読み取れます。このスキルはワークフローではありません。ワークフロースキルを実行して得た知見、つまりコスト、作成のルール、注意点をまとめています。ツールの呼び出しに失敗したときや、結果が返らないとき、どのツールやフィルターを使うべきか迷ったときに参照してください。

パラメーターと REST の完全なリファレンスは、ここでは繰り返しません。末尾の「完全なリファレンス」をご覧ください。

接続と確認

• MCP エンドポイントは https://public-api.tubelab.net/mcp です。ほとんどのクライアントは OAuth で接続します。Cursor やその他の IDE エージェントは、Pro または Team プランが必要な API キーを Authorization: Bearer <key> として送信します。各クライアントのセットアップ方法：https://tubelab.net/docs/api/mcp-server
• 不明な場合は、まず get_credits_balance を呼び出してください。無料です。
• MCP は Starter プランに含まれています。Starter アカウントでは、収益化、収益、RPM、オーディエンスに関するフィールドが空の場合があります。プラン：https://tubelab.net/pricing

ツール一覧

MCP のツール名は REST のパスとは異なり、ツールのスキーマにはコストが表示されません。

ツール	コスト	用途
search_channels	5 クレジット	多数のフィルターを使って、トピック別にチャンネルを検索します。ニッチを見つけるツールです。
search_related_channels	5 クレジット	1 つ以上のチャンネル ID に類似するチャンネルを検索します。競合チャンネルのリストを作成できます。
search_outliers	2 クレジット	チャンネル自体の平均を上回る動画を検索します。現在、何が機能しているかを確認できます。
search_related_outliers	2 クレジット	タイトル、動画、サムネイル（画像から検索する場合は thumbnailVideoId）、またはチャンネルの動画（relatedChannelId）に類似する突出した動画を検索します。
search_trending_formats	1 クレジット	使用状況の統計情報とサンプル動画を添えて、タイトルの定型を検索します。英語のみです。language は渡さないでください。
get_channel、get_channel_videos	無料	同じペイロードを返します。チャンネルの統計情報と、最新順で最大 120 件の長尺動画（突出フラグ付き）を取得します。呼び出しは 1 回で十分です。
get_channel_shorts	無料	突出フラグ付きの Shorts サンプルを取得します。
get_video	無料	タイトル、説明、タグ、公開日、再生回数、高評価数、コメント数を取得します。
get_video_transcript	無料	文字起こしテキストと、タイミング情報付きの events[] を取得します。
get_video_comments	無料	上位コメントを最大 100 件取得します。
get_credits_balance	無料	残りのクレジットを取得します。

各呼び出しのコストは、size にかかわらず同じです。短時間内に同一のリクエストを繰り返しても、再課金されません。フィルターを 1 つ変更すると、新たに課金されます。

ID とリンク

• チャンネル用ツールには、チャンネル 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>。再生位置：同じ URL に &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）を設定し、日付は使いません。結果が少ない場合は、一度に1段階ずつ期間を広げ、その旨をレポートに記載します。
3. コンテンツの信頼性フィルターは有効のままにします。 classificationQuality: "neutral" は「General」以上を意味します。サーバーが「positive」も含めるためです。ニッチ、例外的な事例、アイデア、タイトルに関する作業では neutral を使います。サムネイルに関する作業では「High」を意味する positive を使います。結果が少なくても、このフィルターは外しません。代わりに期間を広げるか、別のフィルターを外します。negative は低労力コンテンツの監査にのみ使います。例外は niche-watchlist で、保存済みの検索ではこのフィルターを指定しません。
4. 生の再生回数より比率を重視します。 averageViewsRatio は、チャンネルの平均に対する再生回数の比率です。この値と zScore から、その形式がうまくいったかどうかが分かります。生の再生回数から分かるのは、チャンネルの規模だけです。比率順に並べ、両方の値を示し、各比率の横にチャンネル登録者数を記載します。
5. デフォルトではセマンティック検索を使います。 by: "semantic" はトピックを理解します。by: "lexical" は完全一致する単語を検索します。query にはトピックの言い換えを1～3個指定し、複数のトピックを列挙しません。
6. ページングの順序を安定させます。 0始まりの結果オフセットである from を使ってページを取得します。2ページ目は from: size です。1回の検索では、すべてのページで同じ seed とフィルターを使います。sortBy を指定しない場合、結果はシードに基づくランダムな順序で返されます。これはアプリの初回読み込み時に表示される順序です。ページを取得するたびに新たな料金が発生します。ユーザーからの依頼、またはスキルでの指定がない限り、ページ数は最大2ページです。niche-finder では、2つのチャンネル検索をそれぞれ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件未満なら、トレンドとはいえません。その旨を伝えて、1度だけ検索範囲を広げます。それでも少なければ、シグナルを捏造せず「シグナルなし」と報告します。
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 で絞り込むよりも、この方法を優先してください。
• ショート動画。 ショート動画チャンネルでは、contentKind: "short-form" と filterBy: "short" を組み合わせ、範囲フィルターがショート動画の統計情報を参照するようにします。ショート動画のみのチャンネルでは、収益化データの精度が低くなります。
• トレンドのフォーマット。 framework は [X] のスロットを含むテンプレートです。pattern は search_outliers の titlePattern として渡す値で、変更せずに使用します。overall_stats.doc_count は、そのフォーマットを使用している動画の数です。検索結果には勢いを示す数値は含まれず、並べ替えキーとしてのみ使われます。そのため、「上昇中」と言えるのは「勢い順のリストに表示される」という意味に限られます。
• Niche Analyzer のスコア。 アプリはニッチのチャンネルのサンプルに対し、各指標の上限を100として、0から100までのスコアを付けます。登録者数が1,000人未満のチャンネルは除外してください。その比率には意味がないためです。Market Size は、各チャンネルで最も視聴された動画の視聴回数 ÷ 1,000,000 × 100 の平均です。Unsaturated は、（平均視聴回数 ÷ 登録者数） ÷ 1.1 × 100 の平均です。Profitable は、低い方の 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を超えるデータが返されます。冒頭部分を確認するには、startMs が45000を超えるまで events[] を読み、その時点で停止してください。文字起こしは話された言語のままです。
• 大きなレスポンス。 チャンネル情報の取得と文字起こしでは、75K文字以上が返されます。必要な情報だけを抽出し、レスポンス全体をそのまま出力しないでください。一部のクライアントは、大きすぎるレスポンスをタイムスタンプで名前付けしたファイルに保存します。また、並列で実行された読み込みによって互いのファイルが上書きされることがあります。大きなデータの取得は一度に1件ずつ行い、保存されたファイルを解析してください。

特記事項とエラー

• 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 のアンカーは正常に動作します。by: "lexical" を指定した search_outliers は、クエリを無視したことがあります。どちらの場合も、それ以上の時間をかける前に、結果がトピックに沿っているか確認してください。
• 外れ値検索の language は音声ではなく、インデックス化されたタイトルの言語に一致します。英語のタグが付いたタイトルでも、動画はヒンディー語、ウルドゥー語、タミル語の場合があります。通常、タイトルの文字体系とサムネイル内のテキストから判別できます。必要な場合は、get_video の defaultAudioLanguage を確認してください。
• channelVideoCountTo の上限は 120 です。チャンネルの動画は 120 件までサンプリングされるためです。titlePattern には * と 2 文字以上を含める必要があります。範囲を指定する場合は、すべて from を to より小さくしてください。
• チャンネルのサンプル日付（publishedAtEstimate）とコメントの日付の精度は月単位です。コメントの高評価数が null になることもよくあります。
• コメントが無効になっている場合、get_video_comments は「Failed Dependency」または「No comments found」を返します。これは失敗ではなく、データなしとして扱ってください。comments[] には重複した項目が含まれることがあるため、投稿者とテキストを基準に重複を除去してください。authorIsChannelOwner は、クリエイターが固定したコメントであっても、すべての行で null が返されています。投稿者のハンドルをチャンネルのハンドルと照合して、クリエイターの返信を見分けてください。
• pagination.total: 0 で hits が空の場合は、対象期間を広げるか、フィルターを 1 つ減らすか、query の表現を変えてください。品質の下限は維持してください。
• pagination.total が size のちょうど 2 倍で返されたことがあります。ニッチの競争の激しさを測るために使わないでください。
• get_channel には、オーディエンス、収益化、収益、RPM のフィールドがありません。これらは検索結果にのみ表示され、チャンネル自体を検索しても結果に含まれないことがあります。
• HTTP 429 はレート制限で、MCP ではセッション間で共有され、ウィンドウあたり約 30 回の呼び出しが上限です。リセットを待ってから再試行してください。読み取りを一度にすべて実行せず、間隔を空けてください。

クレジットの消費

有料検索は候補の発見に使い、無料の読み取りは候補の理解に使ってください。1 件の作業で検索を 2～6 回行うのが妥当な目安です。有料検索をループでページ送りしないでください。サンプルそのものが成果物となるため、より深く調査するスキルが 1 つあります。niche-finder は 2 件のチャンネル検索を、それぞれ 3～4 ページまでページ送りします。検索でエラーが発生した場合は、get_credits_balance を呼び出してから、フィルターを減らして 1 回だけ再試行してください。ユーザーから求められない限り、レポートに予算やクレジット数を記載しないでください。

リファレンス全文

• MCP に接続している場合、ツールスキーマにすべてのパラメーター名と許可される値が記載されています。フィルターを推測する前に確認してください。
• パラメーターの一覧、レスポンスの形式、REST エンドポイント、認証、ページネーション、エラーコードの全容については、https://tubelab.net/docs/skill.md を取得してください。API 仕様から生成されるため、常に最新の状態です。
• スキーマに説明されていないパラメーターが必要な場合、MCP を使わずに REST 経由で作業する場合、またはユーザーから API の仕組みについて尋ねられた場合は、このドキュメントを取得してください。REST 経由でもパラメーター名は同じで、チャンネルのエンドポイントにはハンドルではなくチャンネル ID を指定します。