From f06d10adc3a251ad5a1ac9766a94dc6db7785135 Mon Sep 17 00:00:00 2001 From: therohitdas <43847374+therohitdas@users.noreply.github.com> Date: Sun, 20 Sep 2026 08:33:49 +0000 Subject: [PATCH 1/4] Document all 12 MCP tools + 13 REST endpoints, video/metadata rename The live surface grew from 6 to 12 MCP tools / REST endpoints (get_youtube_video_info + /youtube/info, get_video_metadata + /youtube/video/metadata, get_channel_info + /youtube/channel/info, list_channel_playlists + /youtube/channel/playlists, list_channel_posts + /youtube/channel/posts, get_channel_sections + /youtube/channel/sections), search gained sort/upload_date/duration/ features filters plus channel/playlist/movie search types, and channel/videos gained a tab (videos/shorts/streams) parameter. Update README.md, both skill reference docs (mcp-tools.md, rest-api.md now enumerate the complete surface instead of the old 6/6), SKILL.md's routing table, and every manifest/listing description that hardcoded "6 tools" (plugin.json, the four per-client plugin.json mirrors, marketplace.json, .codex-plugin/plugin.json, smithery.yaml) so they match production. check_conformance.py has no tool-count assertions to update; verified it and skills-ref both still pass locally. Co-Authored-By: CRHQ --- .claude-plugin/marketplace.json | 2 +- .claude-plugin/plugin.json | 2 +- .codex-plugin/plugin.json | 4 +- .cursor-plugin/plugin.json | 2 +- .plugin/plugin.json | 2 +- README.md | 108 ++++++++++++--- marketplace.json | 2 +- plugin.json | 2 +- skills/youtube/SKILL.md | 10 +- skills/youtube/references/mcp-tools.md | 118 +++++++++++++++-- skills/youtube/references/rest-api.md | 175 ++++++++++++++++++++++--- smithery.yaml | 9 +- 12 files changed, 380 insertions(+), 56 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index f29feae..218f99e 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -13,7 +13,7 @@ { "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 comprehensive skill, powered by TranscriptAPI. OAuth sign-in, free tier, no API key to manage.", "version": "1.2.0", "author": { "name": "TranscriptAPI", diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 2dc7cb1..4079c7b 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "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 comprehensive skill, powered by TranscriptAPI. OAuth sign-in, free tier, no API key to manage.", "author": { "name": "TranscriptAPI", "email": "hello@transcriptapi.com", diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 0de6ddd..beb20f1 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "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 comprehensive skill, powered by TranscriptAPI. OAuth sign-in, free tier, no API key to manage.", "author": { "name": "TranscriptAPI", "email": "hello@transcriptapi.com", @@ -28,7 +28,7 @@ "interface": { "displayName": "YouTube MCP + Skill (TranscriptAPI)", "shortDescription": "YouTube MCP + YouTube Skill for AI agents: transcripts, captions, search, channels and playlists.", - "longDescription": "One Agent Plugins 1.0.0 package that gives any compliant agent reliable access to YouTube: video transcripts, timestamped captions and subtitles, video and channel search, within-channel search, channel browsing and playlist contents. Ships a hosted MCP server (6 tools, OAuth 2.1, no key handling) plus a single comprehensive `youtube` skill that routes each request to the right tool, keeps credit spend low, and falls back to the REST API for clients that load skills without MCP. Free tier: 100 credits, no card. TranscriptAPI is a third-party, independent service. It is not affiliated with, endorsed by, or sponsored by YouTube or Google.", + "longDescription": "One Agent Plugins 1.0.0 package that gives any compliant agent reliable access to YouTube: video transcripts, timestamped captions and subtitles, video and channel metadata, video and channel search, within-channel search, channel browsing and playlist contents. Ships a hosted MCP server (12 tools, OAuth 2.1, no key handling) plus a single comprehensive `youtube` skill that routes each request to the right tool, keeps credit spend low, and falls back to the REST API for clients that load skills without MCP. Free tier: 100 credits, no card. TranscriptAPI is a third-party, independent service. It is not affiliated with, endorsed by, or sponsored by YouTube or Google.", "developerName": "TranscriptAPI", "category": "Productivity", "capabilities": [ diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index 2dc7cb1..4079c7b 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -1,7 +1,7 @@ { "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 comprehensive skill, powered by TranscriptAPI. OAuth sign-in, free tier, no API key to manage.", "author": { "name": "TranscriptAPI", "email": "hello@transcriptapi.com", diff --git a/.plugin/plugin.json b/.plugin/plugin.json index 2dc7cb1..4079c7b 100644 --- a/.plugin/plugin.json +++ b/.plugin/plugin.json @@ -1,7 +1,7 @@ { "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 comprehensive skill, powered by TranscriptAPI. OAuth sign-in, free tier, no API key to manage.", "author": { "name": "TranscriptAPI", "email": "hello@transcriptapi.com", diff --git a/README.md b/README.md index bffc685..7315424 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@

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 comprehensive skill.
One install. OAuth sign-in. No API key to manage. Free tier, no card.

@@ -34,7 +34,7 @@ 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:** @@ -45,7 +45,7 @@ Find Andrew Huberman's three most-viewed videos about sleep 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,7 +57,7 @@ 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 | @@ -264,9 +264,11 @@ amp mcp add transcript-api https://transcriptapi.com/mcp --header "Authorization --- -## 🛠️ The 6 MCP tools +## 🛠️ The 12 MCP tools -All six are exposed automatically once you connect. **1 credit = 1 successful (HTTP 200) request.** Failed and rate-limited calls do not consume credits. +All 12 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,19 +312,53 @@ 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. + +| Parameter | Type | Default | Description | +| ----------- | ------ | ------------ | ------------------------------------------------ | +| `video_url` | string | **required** | YouTube URL (full or short) or 11-char video ID | + +**Cost:** Free. -Search YouTube for videos or channels. Filter by type and paginate with a continuation token. +### 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. @@ -332,7 +368,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 +380,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 +444,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 +453,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 diff --git a/marketplace.json b/marketplace.json index f29feae..218f99e 100644 --- a/marketplace.json +++ b/marketplace.json @@ -13,7 +13,7 @@ { "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 comprehensive 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..e659bd9 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 comprehensive 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..16aed61 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** | diff --git a/skills/youtube/references/mcp-tools.md b/skills/youtube/references/mcp-tools.md index 840d4c2..7a684c9 100644 --- a/skills/youtube/references/mcp-tools.md +++ b/skills/youtube/references/mcp-tools.md @@ -1,11 +1,15 @@ # 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. +**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. + --- ## `get_youtube_transcript`: 1 credit @@ -57,17 +61,71 @@ moment. `"text"` is cheaper to reason over. --- +## `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. No credit used. + +| 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: "dQw4w9WgXcQ", 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`. --- @@ -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..2a2f002 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 @@ -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": "dQw4w9WgXcQ", + "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 | | --- | --- | --- | --- | -| `q` | yes | - | 1-200 characters | -| `type` | no | `video` | `video`, `channel` | -| `limit` | no | `20` | 1-50 | +| `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=dQw4w9WgXcQ" -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` | 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 | +Only charged on successful (HTTP 200) responses; 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..c8e96d6 100644 --- a/smithery.yaml +++ b/smithery.yaml @@ -8,10 +8,11 @@ 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. Production-scale + (15M+ requests/month, 49ms median). Authenticate via OAuth (Dynamic Client + Registration) or API key. metadata: homepage: https://transcriptapi.com From 19e064798dcfebc9893ce1d8ce77239b986b80de Mon Sep 17 00:00:00 2001 From: therohitdas <43847374+therohitdas@users.noreply.github.com> Date: Sun, 20 Sep 2026 09:20:56 +0000 Subject: [PATCH 2/4] Swap personal creator handles for safe-list brands in use-case prompts Per the brand-safety rule (examples must use neutral, non-personal brands like @TED/@NASA/@natgeo, never individual creators): replace @lexfridman, @hubermanlab, @veritasium and @MKBHD in the README's example prompts and use-case table with @TED/@NASA/@natgeo, lightly rewording the competitor-analysis row so it still reads naturally. Co-Authored-By: CRHQ --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 7315424..6015d4f 100644 --- a/README.md +++ b/README.md @@ -475,9 +475,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." | --- From b39c802347eacfc56d5f499fd7d99d88acca8a38 Mon Sep 17 00:00:00 2001 From: therohitdas <43847374+therohitdas@users.noreply.github.com> Date: Sun, 20 Sep 2026 09:37:32 +0000 Subject: [PATCH 3/4] fix(copy): flat-cost lines, safe brands, verified stats, dash sweep - Flatten both per-call cost lines to the agreed wording so they don't read as contradicting the FREE tools listed nearby: "Successful calls cost 1 credit unless a tool states otherwise below" (README.md, SKILL.md, mcp-tools.md) and "Successful requests cost 1 credit unless stated otherwise above" (rest-api.md, after the credit-cost table). - Drop the unverified "Production-scale (15M+ requests/month, 49ms median)" claim from smithery.yaml, and the "(15M+ req/mo)" / "Hobbyist scrapers" cells from the README comparison table, re-padding the row. - Drop "comprehensive" from "12 hosted MCP tools plus one comprehensive skill" (and the matching "single comprehensive `youtube` skill" in .codex-plugin/plugin.json) across all 7 files carrying that exact string; kept "no card" and "complete" wording as verified. - Swapped the last personal-creator references and the rickroll placeholder ID (dQw4w9WgXcQ) for a verified one (UF8uR6Z6KLc). Where the old ID co-occurred with matching illustrative title/author/lyrics (mcp-tools.md's get_youtube_transcript example), replaced the whole block with the new video's real metadata (verified via YouTube oEmbed) instead of just swapping the ID, to avoid shipping a factually inconsistent example. - Full em/en dash sweep of every touched file, replaced with hyphen/comma/colon per context; trimmed each FREE tool's redundant free/no-credit prose down to the single header badge mention. Co-Authored-By: CRHQ --- .claude-plugin/marketplace.json | 2 +- .claude-plugin/plugin.json | 2 +- .codex-plugin/plugin.json | 4 +-- .cursor-plugin/plugin.json | 2 +- .plugin/plugin.json | 2 +- README.md | 18 +++++------ marketplace.json | 2 +- plugin.json | 2 +- skills/youtube/SKILL.md | 2 +- skills/youtube/references/mcp-tools.md | 42 +++++++++++++------------- skills/youtube/references/rest-api.md | 20 ++++++------ smithery.yaml | 5 ++- 12 files changed, 51 insertions(+), 52 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 218f99e..2fac210 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -13,7 +13,7 @@ { "name": "transcriptapi", "source": "./", - "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 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/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 4079c7b..ea86ccc 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "transcriptapi", "version": "1.2.0", - "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 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/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index beb20f1..09efc53 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "transcriptapi", "version": "1.2.0", - "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 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", @@ -28,7 +28,7 @@ "interface": { "displayName": "YouTube MCP + Skill (TranscriptAPI)", "shortDescription": "YouTube MCP + YouTube Skill for AI agents: transcripts, captions, search, channels and playlists.", - "longDescription": "One Agent Plugins 1.0.0 package that gives any compliant agent reliable access to YouTube: video transcripts, timestamped captions and subtitles, video and channel metadata, video and channel search, within-channel search, channel browsing and playlist contents. Ships a hosted MCP server (12 tools, OAuth 2.1, no key handling) plus a single comprehensive `youtube` skill that routes each request to the right tool, keeps credit spend low, and falls back to the REST API for clients that load skills without MCP. Free tier: 100 credits, no card. TranscriptAPI is a third-party, independent service. It is not affiliated with, endorsed by, or sponsored by YouTube or Google.", + "longDescription": "One Agent Plugins 1.0.0 package that gives any compliant agent reliable access to YouTube: video transcripts, timestamped captions and subtitles, video and channel metadata, video and channel search, within-channel search, channel browsing and playlist contents. Ships a hosted MCP server (12 tools, OAuth 2.1, no key handling) plus a single `youtube` skill that routes each request to the right tool, keeps credit spend low, and falls back to the REST API for clients that load skills without MCP. Free tier: 100 credits, no card. TranscriptAPI is a third-party, independent service. It is not affiliated with, endorsed by, or sponsored by YouTube or Google.", "developerName": "TranscriptAPI", "category": "Productivity", "capabilities": [ diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index 4079c7b..ea86ccc 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "transcriptapi", "version": "1.2.0", - "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 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/.plugin/plugin.json b/.plugin/plugin.json index 4079c7b..ea86ccc 100644 --- a/.plugin/plugin.json +++ b/.plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "transcriptapi", "version": "1.2.0", - "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 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/README.md b/README.md index 6015d4f..7d2edbd 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@

The complete YouTube toolkit as a single Agent Plugin, by TranscriptAPI.
- 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 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.

@@ -40,8 +40,8 @@ One install gives your agent both halves: **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? ``` @@ -62,7 +62,7 @@ Most YouTube integrations do one thing: pull a single transcript. **This is a fu | 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 | +| Production scale | ✅ Yes | ❌ No | | 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 | @@ -266,7 +266,7 @@ amp mcp add transcript-api https://transcriptapi.com/mcp --header "Authorization ## 🛠️ The 12 MCP tools -All 12 are exposed automatically once you connect. **1 credit = 1 successful (HTTP 200) request.** Failed and rate-limited calls do not consume credits. +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. > **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. @@ -314,7 +314,7 @@ JSON: ### 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. +Basic metadata (title, author, thumbnail) plus the available transcript languages: call before `get_youtube_transcript` to pick a language. | Parameter | Type | Default | Description | | ----------- | ------ | ------------ | ------------------------------------------------ | @@ -360,7 +360,7 @@ A channel's profile: title, `@handle`, verified flag, subscriber/video-count tex ### 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 | | --------- | ------ | ------------ | -------------------------------------------- | @@ -405,7 +405,7 @@ Paginated list of the playlists on a channel (id, title, URL, video-count text, ### 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. +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 | | -------------- | ------ | ------- | ------------------------------------ | @@ -416,7 +416,7 @@ Paginated list of a channel's community (Posts tab) content — text, publish ti ### 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. +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 | | --------- | ------ | ------------ | ---------------------------------------------------------------- | diff --git a/marketplace.json b/marketplace.json index 218f99e..2fac210 100644 --- a/marketplace.json +++ b/marketplace.json @@ -13,7 +13,7 @@ { "name": "transcriptapi", "source": "./", - "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 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 e659bd9..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, video and channel metadata, captions, subtitles, video and channel search, channel browsing and playlist extraction. 12 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 16aed61..6d7e99d 100644 --- a/skills/youtube/SKILL.md +++ b/skills/youtube/SKILL.md @@ -90,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 7a684c9..7c8fae7 100644 --- a/skills/youtube/references/mcp-tools.md +++ b/skills/youtube/references/mcp-tools.md @@ -4,7 +4,7 @@ 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, @@ -31,30 +31,30 @@ 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] I am honored to be with you today at your commencement +[4.12s] from one of the finest universities in the world. ``` **`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": "I am honored to be with you today at your commencement", "start": 0.0, "duration": 4.12 }, + { "text": "from one of the finest universities in the world.", "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" } } ``` @@ -63,8 +63,8 @@ moment. `"text"` is cheaper to reason over. ## `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. No credit used. +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 | | --- | --- | --- | --- | @@ -90,7 +90,7 @@ Hidden counts are `null`, never `0`. When `details` can't be read, `details.avai `false` with a `reason` instead of a guessed value. ```json -get_video_metadata({ video_url: "dQw4w9WgXcQ", include: ["details", "related"] }) +get_video_metadata({ video_url: "UF8uR6Z6KLc", include: ["details", "related"] }) ``` --- @@ -108,7 +108,7 @@ Search YouTube for videos, channels, playlists, or movies. ~20 results per page. | `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 | -Provide either `query` (first call) or `continuation` (next pages) — not both. Filters apply to +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. @@ -123,7 +123,7 @@ keywords, tags, thumbnails, banners, and the tabs it exposes. Not paginated. | --- | --- | --- | --- | | `channel` | string | **required** | `@handle`, channel URL, or `UC…` ID | -Counts are display strings (e.g. `27.8M subscribers`) and `null` when YouTube hides them — +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`. @@ -137,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. --- @@ -187,7 +187,7 @@ 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 +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 | @@ -201,7 +201,7 @@ 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, +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 | @@ -209,7 +209,7 @@ or featured channels, in the channel's own order. Not paginated. | `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 +`podcasts` and `releases` exist only on channels that have them (empty results otherwise: call `get_channel_info` to see a channel's tabs first). --- diff --git a/skills/youtube/references/rest-api.md b/skills/youtube/references/rest-api.md index 2a2f002..4bf2bf3 100644 --- a/skills/youtube/references/rest-api.md +++ b/skills/youtube/references/rest-api.md @@ -40,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": "..." } @@ -49,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" @@ -63,13 +63,13 @@ curl -sG https://transcriptapi.com/api/v2/youtube/transcript \ GET /youtube/info?video_url=VIDEO_URL ``` -Basic metadata (title, author, thumbnail) plus the video's available transcript languages — +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": "dQw4w9WgXcQ", + "video_id": "UF8uR6Z6KLc", "metadata": { "title": "...", "author_name": "...", "author_url": "...", "thumbnail_url": "..." }, "available_languages": [ { "code": "en", "name": "English" }, @@ -91,7 +91,7 @@ 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. +> 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. @@ -108,7 +108,7 @@ 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=dQw4w9WgXcQ" -d include=details,related \ + --data-urlencode "video_url=UF8uR6Z6KLc" -d include=details,related \ -H "Authorization: Bearer $TRANSCRIPT_API_KEY" -H "User-Agent: YourAgent/1.0" ``` @@ -132,7 +132,7 @@ GET /youtube/search?continuation=TOKEN # subsequent pages | `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. +`features`) apply to the first page only: the `continuation` token already encodes them. ~20 results per page. ```bash @@ -219,7 +219,7 @@ 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` +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). @@ -234,7 +234,7 @@ GET /youtube/channel/sections?channel=@TED&tab=featured | `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 +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. @@ -270,7 +270,7 @@ Valid ID prefixes: `PL`, `UU`, `LL`, `FL`, `OL`. Response includes `playlist_inf | `/youtube/channel/sections` | 1 | | `/youtube/playlist/videos` | 1 / page | -Only charged on successful (HTTP 200) responses; failed and rate-limited requests are free. +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 diff --git a/smithery.yaml b/smithery.yaml index c8e96d6..b77e848 100644 --- a/smithery.yaml +++ b/smithery.yaml @@ -10,9 +10,8 @@ startCommand: description: >- 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. Production-scale - (15M+ requests/month, 49ms median). Authenticate via OAuth (Dynamic Client - Registration) or API key. + browsing, playlist extraction, and new-upload polling. Authenticate via + OAuth (Dynamic Client Registration) or API key. metadata: homepage: https://transcriptapi.com From d70b7e33da1c7873bf06499e01b04532c1dcf868 Mon Sep 17 00:00:00 2001 From: therohitdas <43847374+therohitdas@users.noreply.github.com> Date: Sun, 20 Sep 2026 09:58:29 +0000 Subject: [PATCH 4/4] fix: drop deceptive/unverified stats, generic transcript placeholder MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README.md: delete the unverified "15M+ transcripts/month, 500K/day, 49ms median" stat block, and the "Trusted in production by youtubetotranscript.com / recapio.com" line — youtubetotranscript.com is our own product (presenting it as independent social proof is deceptive) and the recapio.com volume figure has no consent/source. - README.md: drop the "Production scale" comparison-matrix row now that it carries no verifiable number. - marketplace.json + .claude-plugin/marketplace.json: strike the trailing "15M+ transcripts/month" claim so the description matches youtube-mcp's (ends at "TranscriptAPI."). - skills/youtube/references/mcp-tools.md: replace the specific quoted transcript lines in the get_youtube_transcript example with clearly generic placeholder text ("First line of transcript" / "Second line of transcript"). The video_id/title/author/thumbnail stay as the verified real metadata for UF8uR6Z6KLc; only the illustrative transcript body is now unambiguously a placeholder, not an invented quote attributed to a real speech. Co-Authored-By: CRHQ --- .claude-plugin/marketplace.json | 2 +- README.md | 4 ---- marketplace.json | 2 +- skills/youtube/references/mcp-tools.md | 8 ++++---- 4 files changed, 6 insertions(+), 10 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 2fac210..98a9560 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -6,7 +6,7 @@ "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": [ diff --git a/README.md b/README.md index 7d2edbd..fa4014e 100644 --- a/README.md +++ b/README.md @@ -21,9 +21,6 @@ MIT License

-> **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? @@ -62,7 +59,6 @@ Most YouTube integrations do one thing: pull a single transcript. **This is a fu | Channel & playlist extraction | ✅ Yes | ❌ No | | Latest-uploads monitoring (free) | ✅ Yes | ❌ No | | OAuth 2.1 + API key auth | ✅ Both | ❌ Usually neither | -| Production scale | ✅ Yes | ❌ No | | 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 | diff --git a/marketplace.json b/marketplace.json index 2fac210..98a9560 100644 --- a/marketplace.json +++ b/marketplace.json @@ -6,7 +6,7 @@ "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": [ diff --git a/skills/youtube/references/mcp-tools.md b/skills/youtube/references/mcp-tools.md index 7c8fae7..c823953 100644 --- a/skills/youtube/references/mcp-tools.md +++ b/skills/youtube/references/mcp-tools.md @@ -36,8 +36,8 @@ moment. `"text"` is cheaper to reason over. # Transcript -[0.0s] I am honored to be with you today at your commencement -[4.12s] from one of the finest universities in the world. +[0.0s] First line of transcript +[4.12s] Second line of transcript ``` **`format="json"`** @@ -47,8 +47,8 @@ moment. `"text"` is cheaper to reason over. "video_id": "UF8uR6Z6KLc", "language": "en", "transcript": [ - { "text": "I am honored to be with you today at your commencement", "start": 0.0, "duration": 4.12 }, - { "text": "from one of the finest universities in the world.", "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": "Steve Jobs' 2005 Stanford Commencement Address",