The complete YouTube toolkit as a single Agent Plugin, by TranscriptAPI.
- YouTube transcripts, captions and subtitles, video & channel search, channel browsing, playlist extraction and new-upload polling: 6 hosted MCP tools plus one comprehensive skill.
+ YouTube transcripts, video & channel metadata, captions and subtitles, video & channel search, channel browsing, playlist extraction and new-upload polling: 12 hosted MCP tools plus one skill.
One install. OAuth sign-in. No API key to manage. Free tier, no card.
-> **Powering 15M+ transcripts every month** ยท 500K+ transcripts processed daily ยท 49ms median response time
-> Trusted in production by [youtubetotranscript.com](https://youtubetotranscript.com) (~11M/mo) and [recapio.com](https://recapio.com) (~2.8M/mo).
-
---
## ๐งฉ What is this?
@@ -34,18 +31,18 @@ One install gives your agent both halves:
| Component | What it does |
|---|---|
-| **MCP server** (`transcriptapi`) | 6 hosted tools over streamable HTTP with OAuth 2.1: `get_youtube_transcript`, `search_youtube`, `get_channel_latest_videos`, `search_channel_videos`, `list_channel_videos`, `list_playlist_videos`. No key handling: your agent signs you in on first use. |
+| **MCP server** (`transcriptapi`) | 12 hosted tools over streamable HTTP with OAuth 2.1: `get_youtube_transcript`, `get_youtube_video_info`, `get_video_metadata`, `search_youtube`, `get_channel_info`, `get_channel_latest_videos`, `search_channel_videos`, `list_channel_videos`, `list_channel_playlists`, `list_channel_posts`, `get_channel_sections`, `list_playlist_videos`. No key handling: your agent signs you in on first use. |
| **Skill** (`youtube`) | Teaches the agent *when* to reach for YouTube data, which tool answers each question, and how not to burn credits, with a full REST fallback for clients that load skills but not MCP servers. |
**Just ask, in plain English:**
```txt
-Summarize this video for me: https://youtu.be/dQw4w9WgXcQ
-Find Andrew Huberman's three most-viewed videos about sleep and compare them.
+Summarize this video for me: https://youtu.be/UF8uR6Z6KLc
+Find @NASA's three most-viewed videos about the Moon landing and compare them.
What has @TED posted in the last month?
```
-That last set of prompts touches 3 of the 6 tools (`search_youtube`, `search_channel_videos`, `get_youtube_transcript`) without you writing a line of code.
+That last set of prompts touches 3 of the 12 tools (`search_youtube`, `search_channel_videos`, `get_youtube_transcript`) without you writing a line of code.
---
@@ -57,12 +54,11 @@ Most YouTube integrations do one thing: pull a single transcript. **This is a fu
| ---------------------------------------- | ----------------- | ------------------- |
| Packaging | โ
Agent Plugins 1.0.0 | โ Per-client manifests |
| Hosting | โ
Remote (no local install) | โ Local stdio install |
-| Tools | โ
6 tools + a skill | โ 1 (transcript only) |
+| Tools | โ
12 tools + a skill | โ 1 (transcript only) |
| YouTube search | โ
Yes | โ No |
| Channel & playlist extraction | โ
Yes | โ No |
| Latest-uploads monitoring (free) | โ
Yes | โ No |
| OAuth 2.1 + API key auth | โ
Both | โ Usually neither |
-| Production scale (15M+ req/mo) | โ
Yes | โ Hobbyist scrapers |
| Works on mobile Claude & web Claude | โ
Yes | โ No |
| Agent-friendly error messages | โ
Yes | โ Bare HTTP codes |
| No yt-dlp, no headless browser, no binaries | โ
Just an API call | โ Blocked on cloud IPs |
@@ -264,9 +260,11 @@ amp mcp add transcript-api https://transcriptapi.com/mcp --header "Authorization
---
-## ๐ ๏ธ The 6 MCP tools
+## ๐ ๏ธ The 12 MCP tools
+
+All 12 are exposed automatically once you connect. **Successful calls cost 1 credit unless a tool states otherwise below.** Failed and rate-limited calls do not consume credits.
-All six are exposed automatically once you connect. **1 credit = 1 successful (HTTP 200) request.** Failed and rate-limited calls do not consume credits.
+> **Which video tool?** Use `get_youtube_video_info` (free) to discover transcript languages before fetching a transcript. Use `get_video_metadata` (1 credit) for view/like counts, publish date, description, duration, tags, or related videos.
### 1. `get_youtube_transcript`
@@ -310,21 +308,55 @@ JSON:
-### 2. `search_youtube`
+### 2. `get_youtube_video_info` ยท **FREE**
+
+Basic metadata (title, author, thumbnail) plus the available transcript languages: call before `get_youtube_transcript` to pick a language.
-Search YouTube for videos or channels. Filter by type and paginate with a continuation token.
+| Parameter | Type | Default | Description |
+| ----------- | ------ | ------------ | ------------------------------------------------ |
+| `video_url` | string | **required** | YouTube URL (full or short) or 11-char video ID |
+
+**Cost:** Free.
+
+### 3. `get_video_metadata`
+
+Rich video metadata without needing captions: view/like-count text, publish date, structured description, channel summary, thumbnails. Optional `include` extras add duration/category/tags/caption tracks and related videos.
+
+| Parameter | Type | Default | Description |
+| ----------- | -------- | ------- | -------------------------------------------------------------------------------------------- |
+| `video_url` | string | **required** | YouTube URL (full or short) or 11-char video ID |
+| `include` | string[] | _none_ | `"details"` (duration, category, tags, caption tracks) and/or `"related"` (related videos) |
+
+**Cost:** 1 credit.
+
+### 4. `search_youtube`
+
+Search YouTube for videos, channels, playlists, or movies. Filter by type, sort, upload date or duration, and paginate with a continuation token.
| Parameter | Type | Default | Description |
| -------------- | ------ | ------------ | ------------------------------------ |
-| `query` | string | **required** | Search query |
-| `search_type` | string | `"video"` | `"video"` or `"channel"` |
+| `query` | string | **required** (first call) | Search query |
+| `search_type` | string | `"video"` | `"video"`, `"channel"`, `"playlist"`, or `"movie"` (first call only) |
+| `sort` | string | `"relevance"` | `"relevance"` or `"views"` (first call only) |
+| `upload_date` | string | _none_ | `hour`, `today`, `week`, `month`, `year` (first call, videos only) |
+| `duration` | string | _none_ | `short`, `medium`, `long` (first call, videos only) |
| `continuation` | string | `null` | Token from a prior call for next page |
**Cost:** 1 credit per page (~20 results).
-### 3. `get_channel_latest_videos` ยท **FREE**
+### 5. `get_channel_info`
+
+A channel's profile: title, `@handle`, verified flag, subscriber/video-count text, description, keywords, tags, thumbnails, banners, and the tabs it exposes.
+
+| Parameter | Type | Default | Description |
+| --------- | ------ | ------------ | --------------------------------------------- |
+| `channel` | string | **required** | `@handle`, channel URL, or `UCโฆ` channel ID |
+
+**Cost:** 1 credit.
+
+### 6. `get_channel_latest_videos` ยท **FREE**
-The ~15 most recent uploads from any channel via RSS. No credits. Perfect for monitoring, daily recaps, or triggering downstream pipelines.
+The ~15 most recent uploads from any channel via RSS. Perfect for monitoring, daily recaps, or triggering downstream pipelines.
| Parameter | Type | Default | Description |
| --------- | ------ | ------------ | -------------------------------------------- |
@@ -332,7 +364,7 @@ The ~15 most recent uploads from any channel via RSS. No credits. Perfect for mo
**Cost:** Free.
-### 4. `search_channel_videos`
+### 7. `search_channel_videos`
Search inside one specific channel for videos matching a query.
@@ -344,18 +376,52 @@ Search inside one specific channel for videos matching a query.
**Cost:** 1 credit per page (~30 results).
-### 5. `list_channel_videos`
+### 8. `list_channel_videos`
-List every video on a channel, ~100 per page. Ideal for building databases or bulk transcript extraction.
+List a channel's feed, paginated. Use `tab` to choose the uploads feed (default, ~100/page), Shorts, or live streams (~48/page). Ideal for building databases or bulk transcript extraction.
| Parameter | Type | Default | Description |
| -------------- | ------ | ------------ | ------------------------------------ |
-| `channel` | string | **required** | `@handle`, channel URL, or `UCโฆ` ID |
+| `channel` | string | **required** (first call) | `@handle`, channel URL, or `UCโฆ` ID |
+| `tab` | string | `"videos"` | `videos` (uploads), `shorts`, or `streams`. Repeat the same `tab` when paginating. |
| `continuation` | string | `null` | Pagination token |
-**Cost:** 1 credit per page (~100 results).
+**Cost:** 1 credit per page.
+
+### 9. `list_channel_playlists`
+
+Paginated list of the playlists on a channel (id, title, URL, video-count text, thumbnails).
+
+| Parameter | Type | Default | Description |
+| -------------- | ------ | ------- | ------------------------------------ |
+| `channel` | string | **required** (first call) | `@handle`, channel URL, or `UCโฆ` ID |
+| `continuation` | string | `null` | Pagination token |
+
+**Cost:** 1 credit per page.
+
+### 10. `list_channel_posts`
+
+Paginated list of a channel's community (Posts tab) content: text, publish time, like-count text, and attachments. Channels without a community tab return an empty results list, not an error.
+
+| Parameter | Type | Default | Description |
+| -------------- | ------ | ------- | ------------------------------------ |
+| `channel` | string | **required** (first call) | `@handle`, channel URL, or `UCโฆ` ID |
+| `continuation` | string | `null` | Pagination token |
+
+**Cost:** 1 credit per page.
+
+### 11. `get_channel_sections`
+
+The curated, grouped sections of a channel page: titled shelves of videos, playlists, shorts, or featured channels, in the channel's own order.
+
+| Parameter | Type | Default | Description |
+| --------- | ------ | ------------ | ---------------------------------------------------------------- |
+| `channel` | string | **required** | `@handle`, channel URL, or `UCโฆ` ID |
+| `tab` | string | `"featured"` | `featured` (Home), `podcasts`, or `releases` |
+
+**Cost:** 1 credit.
-### 6. `list_playlist_videos`
+### 12. `list_playlist_videos`
Every video in a YouTube playlist (PL/UU/LL/FL/OL IDs supported). Process entire courses or lecture series in a single call.
@@ -374,7 +440,7 @@ One skill covers everything. It teaches the agent *when* YouTube is the right so
It handles both data paths automatically:
-- **MCP available** โ drives the 6 hosted tools above. OAuth, no key.
+- **MCP available** โ drives the 12 hosted tools above. OAuth, no key.
- **MCP not available** โ falls back to the REST API with a `TRANSCRIPT_API_KEY`, so the skill still works in clients that load skills but not MCP servers.
Structured for [progressive disclosure](https://agentskills.io/specification#progressive-disclosure), so the agent pays for detail only when it needs it:
@@ -383,7 +449,7 @@ Structured for [progressive disclosure](https://agentskills.io/specification#pro
skills/youtube/
โโโ SKILL.md # routing, credit discipline, workflows (~130 lines)
โโโ references/
- โโโ mcp-tools.md # full parameter reference for the 6 tools
+ โโโ mcp-tools.md # full parameter reference for the 12 tools
โโโ rest-api.md # REST fallback: endpoints, curl, validation rules
โโโ auth-setup.md # getting and persisting an API key
โโโ errors.md # error codes, retry policy, false alarms
@@ -405,9 +471,9 @@ Only `name` + `description` (~100 tokens) load at startup. The body loads when t
| โ๏ธ **Compare perspectives** | "Compare arguments in these two videos: [URL1] [URL2]" |
| ๐ **Translate** | "Translate this video's transcript to Spanish: [URL]" |
| โ๏ธ **Repurpose content** | "Turn this video into a 1,500-word blog post: [URL]" |
-| ๐ก **Monitor a creator** | "Each morning, list new uploads from @hubermanlab and tell me which to watch." |
-| ๐๏ธ **Build a content database** | "Pull every video from @veritasium and store title + transcript." |
-| ๐ฏ **Competitor analysis** | "Search inside @MKBHD for any video about [competitor product] and summarize the takeaways." |
+| ๐ก **Monitor a creator** | "Each morning, list new uploads from @TED and tell me which to watch." |
+| ๐๏ธ **Build a content database** | "Pull every video from @NASA and store title + transcript." |
+| ๐ฏ **Competitor analysis** | "Search inside @NASA for any video about [a specific mission or topic] and summarize the takeaways." |
---
diff --git a/marketplace.json b/marketplace.json
index f29feae..98a9560 100644
--- a/marketplace.json
+++ b/marketplace.json
@@ -6,14 +6,14 @@
"url": "https://transcriptapi.com"
},
"metadata": {
- "description": "YouTube MCP and YouTube Skill packages by TranscriptAPI: 15M+ transcripts/month.",
+ "description": "YouTube MCP and YouTube Skill packages by TranscriptAPI.",
"version": "1.2.0"
},
"plugins": [
{
"name": "transcriptapi",
"source": "./",
- "description": "YouTube MCP + YouTube Skill for AI agents: YouTube transcripts, captions, subtitles, video and channel search, channel browsing and playlist extraction. 6 hosted MCP tools plus one comprehensive skill, powered by TranscriptAPI. OAuth sign-in, free tier, no API key to manage.",
+ "description": "YouTube MCP + YouTube Skill for AI agents: YouTube transcripts, video and channel metadata, captions, subtitles, video and channel search, channel browsing and playlist extraction. 12 hosted MCP tools plus one skill, powered by TranscriptAPI. OAuth sign-in, free tier, no API key to manage.",
"version": "1.2.0",
"author": {
"name": "TranscriptAPI",
diff --git a/plugin.json b/plugin.json
index f5e6d8e..b2d0b2d 100644
--- a/plugin.json
+++ b/plugin.json
@@ -2,7 +2,7 @@
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
"name": "transcriptapi",
"version": "1.2.0",
- "description": "YouTube MCP + YouTube Skill for AI agents: YouTube transcripts, captions, subtitles, video and channel search, channel browsing and playlist extraction. 6 hosted MCP tools plus one comprehensive skill, powered by TranscriptAPI. OAuth sign-in, free tier, no API key to manage.",
+ "description": "YouTube MCP + YouTube Skill for AI agents: YouTube transcripts, video and channel metadata, captions, subtitles, video and channel search, channel browsing and playlist extraction. 12 hosted MCP tools plus one skill, powered by TranscriptAPI. OAuth sign-in, free tier, no API key to manage.",
"author": {
"name": "TranscriptAPI",
"email": "hello@transcriptapi.com",
diff --git a/skills/youtube/SKILL.md b/skills/youtube/SKILL.md
index e5f1731..6d7e99d 100644
--- a/skills/youtube/SKILL.md
+++ b/skills/youtube/SKILL.md
@@ -52,10 +52,16 @@ credits, no card.
| --- | --- | --- | --- |
| What a video says: summarize, quote, transcribe, translate, fact-check | `get_youtube_transcript` | `GET /youtube/transcript` | 1 |
| Captions or subtitles for a video *(same data as a transcript)* | `get_youtube_transcript` | `GET /youtube/transcript` | 1 |
-| Find videos or channels on a topic | `search_youtube` | `GET /youtube/search` | 1 / page |
+| Available transcript languages before spending a credit | `get_youtube_video_info` | `GET /youtube/info` | **free** |
+| View/like counts, publish date, description, duration, tags, related videos | `get_video_metadata` | `GET /youtube/video/metadata` | 1 |
+| Find videos, channels, playlists or movies on a topic | `search_youtube` | `GET /youtube/search` | 1 / page |
+| A channel's profile (subscribers, description, tabs, etc.) | `get_channel_info` | `GET /youtube/channel/info` | 1 |
| What a creator posted recently | `get_channel_latest_videos` | `GET /youtube/channel/latest` | **free** |
| Find something inside one channel | `search_channel_videos` | `GET /youtube/channel/search` | 1 / page |
-| A channel's entire upload history | `list_channel_videos` | `GET /youtube/channel/videos` | 1 / page |
+| A channel's entire upload history, Shorts, or live streams | `list_channel_videos` | `GET /youtube/channel/videos` | 1 / page |
+| The playlists on a channel | `list_channel_playlists` | `GET /youtube/channel/playlists` | 1 / page |
+| A channel's community posts | `list_channel_posts` | `GET /youtube/channel/posts` | 1 / page |
+| A channel's curated Home/podcasts/releases shelves | `get_channel_sections` | `GET /youtube/channel/sections` | 1 |
| Every video in a playlist, course or series | `list_playlist_videos` | `GET /youtube/playlist/videos` | 1 / page |
| Resolve an `@handle` to a `UCโฆ` ID | *(not needed, pass the handle)* | `GET /youtube/channel/resolve` | **free** |
@@ -84,7 +90,7 @@ Full parameters, defaults and response shapes:
## Step 3: spend credits carefully
-1 credit = 1 successful (HTTP 200) request. Failed and rate-limited calls are never charged.
+Successful calls cost 1 credit unless a tool states otherwise below. Failed and rate-limited calls are never charged.
- **`get_channel_latest_videos` is free.** Reach for it first for anything about recent
uploads. Use `list_channel_videos` only when the user genuinely wants the whole catalogue.
diff --git a/skills/youtube/references/mcp-tools.md b/skills/youtube/references/mcp-tools.md
index 840d4c2..c823953 100644
--- a/skills/youtube/references/mcp-tools.md
+++ b/skills/youtube/references/mcp-tools.md
@@ -1,10 +1,14 @@
# MCP tool reference
-The six tools exposed by the bundled `transcriptapi` MCP server
+The 12 tools exposed by the bundled `transcriptapi` MCP server
(`https://transcriptapi.com/mcp`, streamable HTTP, OAuth 2.1).
Authorization is handled by the client. There is no key to pass and no auth argument on any
-tool. 1 credit = 1 successful call; failures and rate limits are never charged.
+tool. Successful calls cost 1 credit unless a tool states otherwise below; failures and rate limits are never charged.
+
+**Which video tool?** Use `get_youtube_video_info` (free) to discover transcript languages
+before fetching a transcript. Use `get_video_metadata` (1 credit) for view/like counts,
+publish date, description, duration, tags, or related videos.
---
@@ -27,47 +31,101 @@ moment. `"text"` is cheaper to reason over.
```markdown
# Metadata
-## Title: Rick Astley - Never Gonna Give You Up
-## Author: RickAstleyVEVO
+## Title: Steve Jobs' 2005 Stanford Commencement Address
+## Author: Stanford
# Transcript
-[0.0s] Never gonna give you up
-[4.12s] Never gonna let you down
+[0.0s] First line of transcript
+[4.12s] Second line of transcript
```
**`format="json"`**
```json
{
- "video_id": "dQw4w9WgXcQ",
+ "video_id": "UF8uR6Z6KLc",
"language": "en",
"transcript": [
- { "text": "Never gonna give you up", "start": 0.0, "duration": 4.12 },
- { "text": "Never gonna let you down", "start": 4.12, "duration": 3.85 }
+ { "text": "First line of transcript", "start": 0.0, "duration": 4.12 },
+ { "text": "Second line of transcript", "start": 4.12, "duration": 3.85 }
],
"metadata": {
- "title": "Rick Astley - Never Gonna Give You Up",
- "author_name": "RickAstleyVEVO",
- "author_url": "https://www.youtube.com/@RickAstley",
- "thumbnail_url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg"
+ "title": "Steve Jobs' 2005 Stanford Commencement Address",
+ "author_name": "Stanford",
+ "author_url": "https://www.youtube.com/@stanford",
+ "thumbnail_url": "https://i.ytimg.com/vi/UF8uR6Z6KLc/maxresdefault.jpg"
}
}
```
---
+## `get_youtube_video_info`: FREE
+
+Basic metadata (title, author, thumbnail) plus the list of available transcript languages:
+call this before `get_youtube_transcript` to pick a language.
+
+| Parameter | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `video_url` | string | **required** | Full URL, short URL, or bare 11-character video ID |
+
+Each returned language code (e.g. `en`, or `asr-en` for auto-generated English) can be passed
+to `get_youtube_transcript`'s `language` parameter. For counts, publish date, description,
+duration, tags, or related videos, use `get_video_metadata` instead.
+
+---
+
+## `get_video_metadata`: 1 credit
+
+Rich video metadata without needing captions: title, view/like-count text, publish date, a
+structured description with extracted links, an uploading-channel summary, and thumbnails.
+
+| Parameter | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `video_url` | string | **required** | Full URL, short URL, or bare 11-character video ID |
+| `include` | string[] | _none_ | `"details"` (duration, category, tags, caption tracks) and/or `"related"` (related videos) |
+
+Hidden counts are `null`, never `0`. When `details` can't be read, `details.available` is
+`false` with a `reason` instead of a guessed value.
+
+```json
+get_video_metadata({ video_url: "UF8uR6Z6KLc", include: ["details", "related"] })
+```
+
+---
+
## `search_youtube`: 1 credit per page
-Search YouTube for videos or channels. ~20 results per page.
+Search YouTube for videos, channels, playlists, or movies. ~20 results per page.
| Parameter | Type | Default | Notes |
| --- | --- | --- | --- |
-| `query` | string | **required** | 1-200 characters |
-| `search_type` | string | `"video"` | `"video"` or `"channel"` |
+| `query` | string | **required** (first call) | 1-200 characters |
+| `search_type` | string | `"video"` | `"video"`, `"channel"`, `"playlist"`, or `"movie"` (first call only) |
+| `sort` | string | `"relevance"` | `"relevance"` or `"views"` (first call only) |
+| `upload_date` | string | _none_ | `hour`, `today`, `week`, `month`, `year` (first call, videos only) |
+| `duration` | string | _none_ | `short` (under 4m), `medium` (4-20m), `long` (over 20m) (first call, videos only) |
| `continuation` | string | `null` | Token from a prior call, for the next page |
-Returns metadata only, no transcripts. Pick the best hits, then transcribe those.
+Provide either `query` (first call) or `continuation` (next pages), not both. Filters apply to
+the first call only; the `continuation` token already encodes them. Returns metadata only, no
+transcripts. Pick the best hits, then transcribe those.
+
+---
+
+## `get_channel_info`: 1 credit
+
+A channel's profile: title, `@handle`, verified flag, subscriber/video-count text, description,
+keywords, tags, thumbnails, banners, and the tabs it exposes. Not paginated.
+
+| Parameter | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `channel` | string | **required** | `@handle`, channel URL, or `UCโฆ` ID |
+
+Counts are display strings (e.g. `27.8M subscribers`) and `null` when YouTube hides them,
+never `0`. Check `availableTabs` before calling `get_channel_sections` or `list_channel_videos`
+with a `tab`.
---
@@ -79,7 +137,7 @@ The ~15 most recent uploads from a channel, via RSS.
| --- | --- | --- | --- |
| `channel` | string | **required** | `@handle`, channel URL, or `UCโฆ` ID |
-Costs nothing. Use it freely for anything about recent uploads, monitoring, or daily recaps.
+Use it freely for anything about recent uploads, monitoring, or daily recaps.
Returns exact view counts and ISO publish timestamps.
---
@@ -100,11 +158,13 @@ Always better than listing a whole channel and filtering client-side.
## `list_channel_videos`: 1 credit per page
-A channel's full upload history, ~100 per page.
+A channel's feed, paginated. Use `tab` to choose the uploads feed (default, ~100/page), Shorts,
+or live streams (~48/page).
| Parameter | Type | Default | Notes |
| --- | --- | --- | --- |
-| `channel` | string | **required** | `@handle`, channel URL, or `UCโฆ` ID |
+| `channel` | string | **required** (first call) | `@handle`, channel URL, or `UCโฆ` ID |
+| `tab` | string | `"videos"` | `videos` (uploads), `shorts`, or `streams`. Repeat the same `tab` when paginating. |
| `continuation` | string | `null` | Pagination token |
Only when the user genuinely wants the whole catalogue. For recent uploads use
@@ -112,13 +172,55 @@ Only when the user genuinely wants the whole catalogue. For recent uploads use
---
+## `list_channel_playlists`: 1 credit per page
+
+Paginated list of the playlists on a channel (id, title, URL, video-count text, thumbnails).
+
+| Parameter | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `channel` | string | **required** (first call) | `@handle`, channel URL, or `UCโฆ` ID |
+| `continuation` | string | `null` | Pagination token |
+
+Pass a returned playlist id to `list_playlist_videos` to get its videos.
+
+---
+
+## `list_channel_posts`: 1 credit per page
+
+Paginated list of a channel's community (Posts tab) content: text, publish time, like-count
+text, and attachments (image, multi-image, video, playlist, or poll).
+
+| Parameter | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `channel` | string | **required** (first call) | `@handle`, channel URL, or `UCโฆ` ID |
+| `continuation` | string | `null` | Pagination token |
+
+Channels without a community tab return an empty results list (not an error).
+
+---
+
+## `get_channel_sections`: 1 credit
+
+The curated, grouped sections of a channel page: titled shelves of videos, playlists, shorts,
+or featured channels, in the channel's own order. Not paginated.
+
+| Parameter | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `channel` | string | **required** | `@handle`, channel URL, or `UCโฆ` ID |
+| `tab` | string | `"featured"` | `featured` (Home), `podcasts`, or `releases` |
+
+`podcasts` and `releases` exist only on channels that have them (empty results otherwise: call
+`get_channel_info` to see a channel's tabs first).
+
+---
+
## `list_playlist_videos`: 1 credit per page
Every video in a playlist, ~100 per page.
| Parameter | Type | Default | Notes |
| --- | --- | --- | --- |
-| `playlist` | string | **required** | Playlist URL or ID: `PL`, `UU`, `LL`, `FL`, `OL` prefixes |
+| `playlist` | string | **required** (first call) | Playlist URL or ID: `PL`, `UU`, `LL`, `FL`, `OL` prefixes |
| `continuation` | string | `null` | Pagination token |
Confirm before transcribing a large playlist: that is one credit per video.
diff --git a/skills/youtube/references/rest-api.md b/skills/youtube/references/rest-api.md
index e5a3cc4..4bf2bf3 100644
--- a/skills/youtube/references/rest-api.md
+++ b/skills/youtube/references/rest-api.md
@@ -32,6 +32,7 @@ GET /youtube/transcript?video_url=VIDEO_URL&format=text&include_timestamp=true&s
| `format` | no | `json` | `json`, `text` |
| `include_timestamp` | no | `true` | `true`, `false` |
| `send_metadata` | no | `false` | `true`, `false` |
+| `language` | no | - | Priority list of transcript language codes |
Note the REST defaults differ from the MCP tool's: pass
`format=text&include_timestamp=true&send_metadata=true` explicitly unless the user asked
@@ -39,7 +40,7 @@ otherwise.
```json
{
- "video_id": "dQw4w9WgXcQ",
+ "video_id": "UF8uR6Z6KLc",
"language": "en",
"transcript": [{ "text": "...", "start": 18.0, "duration": 3.5 }],
"metadata": { "title": "...", "author_name": "...", "author_url": "..." }
@@ -48,7 +49,7 @@ otherwise.
```bash
curl -sG https://transcriptapi.com/api/v2/youtube/transcript \
- --data-urlencode "video_url=https://youtu.be/dQw4w9WgXcQ" \
+ --data-urlencode "video_url=https://youtu.be/UF8uR6Z6KLc" \
-d format=text -d include_timestamp=true -d send_metadata=true \
-H "Authorization: Bearer $TRANSCRIPT_API_KEY" \
-H "User-Agent: YourAgent/1.0"
@@ -56,17 +57,89 @@ curl -sG https://transcriptapi.com/api/v2/youtube/transcript \
---
-## Search: 1 credit
+## Video info: FREE
```http
-GET /youtube/search?q=QUERY&type=video&limit=20
+GET /youtube/info?video_url=VIDEO_URL
```
-| Param | Required | Default | Validation |
+Basic metadata (title, author, thumbnail) plus the video's available transcript languages:
+call this **before** `/youtube/transcript` to pick a language. No credit used (still requires
+an active plan). Returns `404` when the video does not exist or has no captions.
+
+```json
+{
+ "video_id": "UF8uR6Z6KLc",
+ "metadata": { "title": "...", "author_name": "...", "author_url": "...", "thumbnail_url": "..." },
+ "available_languages": [
+ { "code": "en", "name": "English" },
+ { "code": "asr-en", "name": "English (auto-generated)" }
+ ]
+}
+```
+
+Each `available_languages[].code` can be passed to `/youtube/transcript`'s `language` param.
+For counts, publish date, description, duration, tags, or related videos, use
+`/youtube/video/metadata` instead.
+
+---
+
+## Video metadata: 1 credit
+
+```http
+GET /youtube/video/metadata?video_url=VIDEO_URL&include=details,related
+```
+
+> **Naming:** this endpoint was previously `/youtube/video/info`. That path still works as a
+> hidden, deprecated alias: always call `/youtube/video/metadata` in new code.
+
+Rich video metadata without needing captions: title, view/like-count text, publish date, a
+structured description with extracted links, an uploading-channel summary, and thumbnails.
+
+| Param | Required | Default | Values |
+| --- | --- | --- | --- |
+| `video_url` | yes | - | YouTube URL or 11-character video ID |
+| `include` | no | - | Comma-separated: `details`, `related` |
+
+`include=details` adds a `details` object (`lengthSeconds`, `category`, `tags`, caption-track
+inventory) sourced from YouTube's player endpoint; when it can't be read, `details.available`
+is `false` with a `reason` instead of a guessed value. `include=related` adds a `related` list
+of suggested videos. Hidden counts are `null`, never `0`. Cached 5 minutes.
+
+```bash
+curl -sG https://transcriptapi.com/api/v2/youtube/video/metadata \
+ --data-urlencode "video_url=UF8uR6Z6KLc" -d include=details,related \
+ -H "Authorization: Bearer $TRANSCRIPT_API_KEY" -H "User-Agent: YourAgent/1.0"
+```
+
+---
+
+## Search: 1 credit per page
+
+```http
+GET /youtube/search?q=QUERY&type=video
+GET /youtube/search?continuation=TOKEN # subsequent pages
+```
+
+| Param | Required | Default | Values |
| --- | --- | --- | --- |
-| `q` | yes | - | 1-200 characters |
-| `type` | no | `video` | `video`, `channel` |
-| `limit` | no | `20` | 1-50 |
+| `q` | conditional | - | 1-200 characters. Required for the first page. |
+| `type` | no | `video` | `video`, `channel`, `playlist`, `movie` (first page only) |
+| `sort` | no | `relevance` | `relevance`, `views` (first page only) |
+| `upload_date` | no | - | `hour`, `today`, `week`, `month`, `year` (first page, videos only) |
+| `duration` | no | - | `short` (under 4m), `medium` (4-20m), `long` (over 20m) (first page, videos only) |
+| `features` | no | - | Comma-separated: `hd`, `subtitles`, `cc`, `live`, `4k`, `hdr`, `360`, `creative_commons` (first page only) |
+| `continuation` | conditional | - | Token from a prior call, for the next page |
+
+Provide exactly one of `q` or `continuation`. Filters (`sort`, `upload_date`, `duration`,
+`features`) apply to the first page only: the `continuation` token already encodes them.
+~20 results per page.
+
+```bash
+curl -sG https://transcriptapi.com/api/v2/youtube/search \
+ --data-urlencode "q=machine learning explained" -d type=video -d sort=views -d duration=long \
+ -H "Authorization: Bearer $TRANSCRIPT_API_KEY" -H "User-Agent: YourAgent/1.0"
+```
---
@@ -85,6 +158,16 @@ GET /youtube/channel/resolve?input=@TED
{ "channel_id": "UC...", "resolved_from": "@TED" }
```
+### Channel info: 1 credit
+
+```http
+GET /youtube/channel/info?channel=@TED
+```
+
+Profile: title, `@handle`, verified flag, subscriber/video-count text, description, keywords,
+tags, thumbnails, banners, and `availableTabs`. Not paginated. Check `availableTabs` before
+calling `/youtube/channel/sections` or `/youtube/channel/videos` with a `tab`.
+
### Latest ~15 videos: FREE
```http
@@ -93,22 +176,68 @@ GET /youtube/channel/latest?channel=@TED
Returns exact `viewCount` and ISO `published` timestamps.
-### All channel videos: 1 credit per page
+### Channel videos (paginated): 1 credit per page
```http
GET /youtube/channel/videos?channel=@NASA # first page, ~100 videos
+GET /youtube/channel/videos?channel=@NASA&tab=shorts
GET /youtube/channel/videos?continuation=TOKEN # subsequent pages
```
+| Param | Required | Default | Values |
+| --- | --- | --- | --- |
+| `channel` | conditional | - | first page only |
+| `tab` | no | `videos` | `videos` (uploads), `shorts`, `streams`. Repeat the same `tab` when paginating. |
+| `continuation` | conditional | - | subsequent pages |
+
Provide **exactly one** of `channel` or `continuation`. The response carries
`continuation_token` and `has_more`.
-### Search within a channel: 1 credit
+### Search within a channel: 1 credit per page
+
+```http
+GET /youtube/channel/search?channel=@TED&q=QUERY
+GET /youtube/channel/search?continuation=TOKEN
+```
+
+~30 results per page.
+
+### Channel playlists: 1 credit per page
+
+```http
+GET /youtube/channel/playlists?channel=@TED
+GET /youtube/channel/playlists?continuation=TOKEN
+```
+
+Returns id, title, URL, video-count text, thumbnails for each playlist. Pass a returned
+`playlistId` to `/youtube/playlist/videos` to list its videos.
+
+### Channel posts: 1 credit per page
```http
-GET /youtube/channel/search?channel=@TED&q=QUERY&limit=30
+GET /youtube/channel/posts?channel=@TED
+GET /youtube/channel/posts?continuation=TOKEN
```
+Community (Posts tab) content: text, publish time, like-count text, and an `attachment`
+(`image`, `multi_image`, `video`, `playlist`, or `poll`). Channels without a community tab
+return an empty `results` list (HTTP 200, not an error).
+
+### Channel sections: 1 credit
+
+```http
+GET /youtube/channel/sections?channel=@TED&tab=featured
+```
+
+| Param | Required | Default | Values |
+| --- | --- | --- | --- |
+| `channel` | yes | - | `@handle`, channel URL, or `UCโฆ` ID |
+| `tab` | no | `featured` | `featured` (Home), `podcasts`, `releases` |
+
+The curated, grouped shelves of a channel page, in the channel's own order: each shelf holds
+videos, playlists, shorts, or featured channels. Not paginated. `podcasts`/`releases` return
+empty results on channels that don't have them.
+
---
## Playlists: 1 credit per page
@@ -119,7 +248,7 @@ GET /youtube/playlist/videos?continuation=TOKEN # subsequent pages
```
Valid ID prefixes: `PL`, `UU`, `LL`, `FL`, `OL`. Response includes `playlist_info`, `results`,
-`continuation_token` and `has_more`.
+`continuation_token` and `has_more`. ~100 results per page.
---
@@ -128,13 +257,22 @@ Valid ID prefixes: `PL`, `UU`, `LL`, `FL`, `OL`. Response includes `playlist_inf
| Endpoint | Cost |
| --- | --- |
| `/youtube/transcript` | 1 |
-| `/youtube/search` | 1 |
+| `/youtube/info` | **free** |
+| `/youtube/video/metadata` | 1 |
+| `/youtube/search` | 1 / page |
| `/youtube/channel/resolve` | **free** |
+| `/youtube/channel/info` | 1 |
| `/youtube/channel/latest` | **free** |
| `/youtube/channel/videos` | 1 / page |
-| `/youtube/channel/search` | 1 |
+| `/youtube/channel/search` | 1 / page |
+| `/youtube/channel/playlists` | 1 / page |
+| `/youtube/channel/posts` | 1 / page |
+| `/youtube/channel/sections` | 1 |
| `/youtube/playlist/videos` | 1 / page |
+Successful requests cost 1 credit unless stated otherwise above. Failed and rate-limited requests are free.
+Free endpoints still require an active plan with at least one credit available.
+
## Validation rules
| Field | Rule |
@@ -143,17 +281,24 @@ Valid ID prefixes: `PL`, `UU`, `LL`, `FL`, `OL`. Response includes `playlist_inf
| `channel` | `@handle`, channel URL, or `UCโฆ` ID |
| `playlist` | Playlist URL or ID with a `PL`/`UU`/`LL`/`FL`/`OL` prefix |
| `q` | 1-200 characters |
-| `limit` | 1-50 |
+| `type` (search) | `video`, `channel`, `playlist`, `movie` |
+| `tab` (channel/videos) | `videos`, `shorts`, `streams` |
+| `tab` (channel/sections) | `featured`, `podcasts`, `releases` |
## Worked example: research workflow
```bash
# 1. find candidates
curl -sG https://transcriptapi.com/api/v2/youtube/search \
- --data-urlencode "q=machine learning explained" -d limit=5 \
+ --data-urlencode "q=machine learning explained" -d type=video \
+ -H "Authorization: Bearer $TRANSCRIPT_API_KEY" -H "User-Agent: YourAgent/1.0"
+
+# 2. check languages before spending a credit (optional, free)
+curl -sG https://transcriptapi.com/api/v2/youtube/info \
+ --data-urlencode "video_url=VIDEO_ID" \
-H "Authorization: Bearer $TRANSCRIPT_API_KEY" -H "User-Agent: YourAgent/1.0"
-# 2. transcribe only the ones worth reading
+# 3. transcribe only the ones worth reading
curl -sG https://transcriptapi.com/api/v2/youtube/transcript \
--data-urlencode "video_url=VIDEO_ID" \
-d format=text -d include_timestamp=true -d send_metadata=true \
diff --git a/smithery.yaml b/smithery.yaml
index c0407bb..b77e848 100644
--- a/smithery.yaml
+++ b/smithery.yaml
@@ -8,10 +8,10 @@ startCommand:
type: http
url: https://transcriptapi.com/mcp
description: >-
- YouTube transcripts + YouTube search MCP for AI agents. Six tools: transcript
- extraction, video search, channel search, channel browsing, playlist
- extraction, and new-upload polling. Production-scale (15M+ requests/month,
- 49ms median). Authenticate via OAuth (Dynamic Client Registration) or API key.
+ YouTube transcripts + YouTube search MCP for AI agents. 12 tools: transcript
+ extraction, video & channel metadata, video search, channel search, channel
+ browsing, playlist extraction, and new-upload polling. Authenticate via
+ OAuth (Dynamic Client Registration) or API key.
metadata:
homepage: https://transcriptapi.com