tubelab-mcp

TubeLab MCP: the data layer

TubeLab is a read-only index of public YouTube data. It holds breakout channels, outlier videos and trending title formulas, refreshed daily, plus live reads of channels, videos, transcripts and comments. This skill is not a workflow. It holds what we learned by running the workflow skills: costs, craft rules and quirks. Open it when a tool call fails or returns nothing, or when you are unsure which tool or filter to use.

The full parameter and REST reference is not repeated here. See "Full reference" at the end.

Connect and check

• The MCP endpoint is https://public-api.tubelab.net/mcp. Most clients connect with OAuth. Cursor and other IDE agents send an API key as Authorization: Bearer <key>, which needs a Pro or Team plan. Setup for each client: https://tubelab.net/docs/api/mcp-server
• When unsure, call get_credits_balance first. It is free.
• The MCP is included from the Starter plan. Monetization, revenue, RPM and audience fields can be empty on Starter accounts. Plans: https://tubelab.net/pricing

Tool map

The MCP tool names differ from the REST paths, and the tool schemas do not show costs.

Tool	Cost	Use it for
search_channels	5 credits	Channels by topic, with many filters. The niche-finding tool.
search_related_channels	5 credits	Channels similar to one or more channel IDs. Competitor sets.
search_outliers	2 credits	Videos that beat their own channel's average. What is working now.
search_related_outliers	2 credits	Outliers similar to a title, a video, a thumbnail (thumbnailVideoId, by image) or a channel's videos (relatedChannelId).
search_trending_formats	1 credit	Title formulas with usage stats and example videos. English only. Pass no language.
get_channel, get_channel_videos	free	The same payload: channel stats plus up to 120 long-form videos, newest first, with outlier flags. One call is enough.
get_channel_shorts	free	A sample of Shorts with outlier flags.
get_video	free	Title, description, tags, publish date, views, likes and comment count.
get_video_transcript	free	Transcript text plus timed events[].
get_video_comments	free	Up to 100 top comments.
get_credits_balance	free	Remaining credits.

Each call costs the same whatever its size. Repeating an identical request within a short window is not charged again. Changing one filter is a new charge.

Identifiers and links

• Channel tools accept a channel ID (UC...), a URL or a handle (@name). Prefer the ID when a search hit already gave it.
• Video tools need the bare 11-character video ID. Take it from watch?v=ID, youtu.be/ID, shorts/ID or embed/ID, and strip &t= and other parameters.
• Search hits carry id (the video) and snippet.channelId. Use those. Never guess an ID.
• Build report links only from tool data. Video: https://www.youtube.com/watch?v=<id>. Moment: the same plus &t=<seconds>s, where seconds are startMs divided by 1000. Channel: https://www.youtube.com/@<handle>, or https://www.youtube.com/channel/<channelId> when there is no handle. Brands, products and offers: the URL as read in a description, or the video moment where they were only heard.

Craft rules

1. Broad, then narrow. Start with one wide search and read what comes back. Then add filters. Six filters on the first call often return nothing, and they cost the same.
2. Recency first. Always set publishedAtFrom with a token: month, trimester, semester or year, never a date. If results are thin, widen one step at a time and say so in the report.
3. Content Authenticity stays on. classificationQuality: "neutral" means General and above, because the server includes positive. Use neutral for niche, outlier, idea and title work. Use positive (High) for anything about thumbnails. Never drop it to widen a thin result. Widen recency or remove another filter instead. negative is only for auditing low-effort content. niche-watchlist is the exception: its saved search leaves the filter out.
4. Ratio over raw views. averageViewsRatio is views divided by the channel's average. It and zScore say whether a format worked. Raw views only say the channel is big. Rank by ratio, show both, and keep the channel's subscriber count next to every ratio.
5. Semantic by default. by: "semantic" understands topics. by: "lexical" matches exact words. query takes 1 to 3 phrasings of one topic, not a list of topics.
6. Stable paging. Page with from, a 0-based result offset, so page 2 is from: size. Keep the same seed and filters on every page of one search. With no sortBy, results come in seeded-random order, which is what the app shows on first load. Each page is a new charge. Two pages is the ceiling unless the user asks or the skill says so. niche-finder pages its two channel searches 3 to 4 pages deep.
7. Exclude low-effort niches. Pair the quality floor with excludeNiche on channel searches or excludeKeyword on outlier searches. Start from this list, drop what belongs to the user's niche, and add the user's own: music, song, lofi, movies, trailer, compilation, kids, nursery, news, politics, lingerie, haul, asmr, reaction, live stream.
8. Estimates are estimates. Revenue, RPM and audience fields are model outputs. Use them to order results and show them as bands. Never quote them as facts, and do not filter on them unless asked.
9. Thin signal. Fewer than 5 hits is not a trend. Say so and widen once. If it is still thin, report "no signal" instead of inventing one.
10. Proof line. Every claim about a channel or video carries channel (handle) · video title verbatim · views · ratio · publish date. Link everything you cite, with a URL from tool data. A sponsor that was only heard links to its video moment. Label estimates. If you did not fetch it, you do not know it.

Reading results

• What to trust on a channel hit. Cluster channels on semantic.niches[]. Median views show demand; the average is pulled up by outliers. A views-to-subscribers ratio above 1 means the algorithm shows the channel beyond its subscribers. A variation coefficient under 1 means steady views, and above 1.5 means a few hits carry the channel. Outlier counts cannot be filtered on, so read positiveOutliersCount on each hit.
• Index values against live reads. A search hit's statistics come from the index. A get_channel read is live. The two can differ a lot on small or young channels. When you read a channel, use the live value and say which one you used.
• App default views. The Niche Finder opens with subscribersFrom: 1, medianViewsFrom: 1000, videosCountFrom: 2 and no sort. The Outliers Finder opens with viewCountFrom: 5000, type: "video" and no sort. Use these settings to get the same unbiased sample the user sees in the app.
• Dates on channels. joinedDateFrom is when the channel was created. sortBy: "foundAt" orders by when TubeLab first found the channel.
• Faceless flags are predictions. Check them on the thumbnails when it matters.
• Sponsors. The public API strips the sponsored flag inside monetization. Read detections.sponsored.detected instead.
• First-world audiences. RPM estimates are most reliable for these. Filter on audienceRegion 021 (Northern America), 154 (Northern Europe), 155 (Western Europe) and 053 (Australia and New Zealand), with income upper_middle or high. Prefer this to filtering on RPM.
• Shorts. For Shorts channels, pair contentKind: "short-form" with filterBy: "short", so range filters read the Shorts statistics. Monetization data is less accurate on Shorts-only channels.
• Trending formats. framework is the template with [X] slots. pattern is the value to pass as titlePattern to search_outliers, unchanged. overall_stats.doc_count is the number of videos using it. The hit does not carry momentum numbers; they are only sort keys. So "rising" can only mean "appears in the momentum-sorted list".
• Niche Analyzer scores. The app scores a sample of a niche's channels from 0 to 100, each capped at 100. Leave channels under 1,000 subscribers out, because their ratios mean nothing. Market Size is the average of each channel's most-viewed video ÷ 1,000,000 × 100. Unsaturated is the average of (average views ÷ subscribers) ÷ 1.1 × 100. Profitable is the average low RPM estimate ÷ 7 × 100. Under 50 is weak, 50 to 70 is fair, and 71 and above is strong.
• Thumbnails. A video hit carries thumbnails.high.url; on a channel hit that field is the avatar. Any video ID also works with https://i.ytimg.com/vi/<id>/hqdefault.jpg. In a report, show the 320-pixel https://i.ytimg.com/vi/<id>/mqdefault.jpg. It exists for every video and keeps reports compact; maxresdefault.jpg has returned 404. The tools return a link, not the picture, so always download and open the thumbnail of every video you analyze. If an image truly cannot be fetched, say it was not viewed, and never describe it unseen.
• Transcripts. A 30-minute video returns over 100KB. For a hook, read events[] until startMs passes 45000, then stop. Transcripts keep the spoken language.
• Large responses. Channel reads and transcripts run 75K characters and up. Extract what you need and never echo them. Some clients save oversized responses to a file named by timestamp, and reads fired in parallel have overwritten each other's file. Fetch large reads one at a time and parse the saved file.

Quirks and errors

• search_trending_formats rejects language with "Expected string, received array". The MCP schema lists language as an array for every search tool, but this backend wants a string. Leave it out; the default is English.
• When left out, search_trending_formats defaults to English, quality: "positive", videosCountFrom: 18, sorting by lastVideosCountChangePercentage, size: 12, and formulas found in the last 4 months.
• search_related_channels ranks by similarity, not size. A large seed channel returns small lookalikes unless you add subscribersFrom.
• High viewCountFrom floors on search_outliers surface paid brand campaigns, with ratios of 50 and more. Add channelMonetizationAdsense: true or remove them by hand.
• search_related_outliers with a title anchor has returned off-topic hits and ignored publishedAtFrom and classificationQuality. The videoId, thumbnailVideoId and relatedChannelId anchors behave. search_outliers with by: "lexical" has ignored the query. In both cases, check the hits are on topic before spending more.
• language on outlier searches matches the indexed title language, not the audio. English-tagged titles can be Hindi, Urdu or Tamil videos. The title script and thumbnail text usually reveal it. Check defaultAudioLanguage from get_video when it matters.
• channelVideoCountTo caps at 120, because channels are sampled to 120 videos. titlePattern must contain * and at least two letters. Every range needs from below to.
• Channel sample dates (publishedAtEstimate) and comment dates are only accurate to the month. Comment like counts are often null.
• get_video_comments returns "Failed Dependency" or "No comments found" when comments are disabled. Treat that as no data, not a failure. Its comments[] can repeat entries, so dedupe on author plus text. authorIsChannelOwner has come back null on every row, even on the creator's pinned comments. Spot the creator's replies by matching the author handle to the channel's.
• Empty hits with pagination.total: 0: widen recency, drop one filter or rephrase query. Keep the quality floor.
• pagination.total has come back as exactly twice size. Do not use it to measure how crowded a niche is.
• get_channel has no audience, monetization, revenue or RPM fields. Those appear only on search hits, and a channel may not appear in a search for itself.
• HTTP 429 is the rate limit, about 30 calls per window on the MCP, shared across sessions. Wait for the reset and retry. Pace reads rather than firing them all at once.

Spending credits

Spend paid searches on finding candidates and free reads on understanding them. Two to six searches per job is a sane norm, and a paid search is not paged in a loop. One skill goes deeper, because the sample is the product: niche-finder pages two channel searches 3 to 4 pages deep. If a search errors, call get_credits_balance, then retry once with fewer filters. Keep budgets and credit counts out of the report; give them if the user asks.

Full reference

• When connected to the MCP, the tool schemas list every parameter name and allowed value. Read them before guessing a filter.
• For the full parameter list, response shapes, REST endpoints, authentication, pagination and error codes, fetch https://tubelab.net/docs/skill.md. It is generated from the API spec, so it stays current.
• Fetch it when you need a parameter the schema does not explain, when you work without the MCP over REST, or when the user asks how the API works. Over REST, the parameter names are the same, and channel endpoints take a channel ID, not a handle.