An MCP server (stdio; remote HTTP/SSE via mcp-proxy) that fetches video transcripts/subtitles via yt-dlp, with pagination for large responses. Supports YouTube, Twitter/X, Instagram, TikTok, Twitch, Vimeo, Facebook, Bilibili, VK, Dailymotion, Reddit. Whisper fallback — transcribes audio when subtitles are unavailable (local or OpenAI API). Works with Cursor and other MCP hosts.
This repository primarily ships a stdio MCP server (node dist/mcp.js):
stdio: for local usage (e.g., Cursor running a local command).
Remote HTTP/SSE: expose stdio through mcp-proxy (e.g. VPS + Tailscale); see MCP quick start and docker-compose.example.yml.
It also includes an optional REST API (Fastify), but MCP is the primary focus.
Related MCP server: YouTube MCP
Unlike YouTube-only tools, Transcriptor MCP works across 11 major video platforms:
YouTube · Twitter/X · Instagram · TikTok · Twitch · Vimeo · Facebook · Bilibili · VK · Dailymotion · Reddit
All URL-based tools (get_transcript, get_raw_subtitles, get_available_subtitles, get_video_info, get_video_chapters, get_playlist_transcripts) accept video URLs from any supported platform. The search_videos tool is YouTube-specific (yt-dlp ytsearch).
Transcriptor MCP is the best choice when you need transcripts and metadata for AI, summarization, or content analysis — without downloading video or audio files:
Transcripts and subtitles — cleaned text or raw SRT/VTT; multi-language; Whisper fallback when subtitles are unavailable (local or OpenAI).
Multi-platform — YouTube, Twitter/X, Instagram, TikTok, Twitch, Vimeo, Facebook, Bilibili, VK, Dailymotion, Reddit.
Remote and production — stdio + mcp-proxy for HTTP/SSE, optional auth at the edge, Redis cache, Prometheus metrics on the REST API; connect without a local install via Smithery using a session apiToken.
No media downloads — we focus on text and metadata only. For downloading videos or audio.
Use the sections in this README for setup, tools, and deployment patterns.
Choose one of these two main paths:
Best when you want a fast local setup without Node on host.
docker run --rm -i artsamsonov/transcriptor-mcp:latestCursor MCP config:
{
"mcpServers": {
"transcriptor": {
"command": "docker",
"args": ["run", "--rm", "-i", "artsamsonov/transcriptor-mcp:latest"]
}
}
}Detailed local + self-hosted HTTP/SSE instructions are in How to connect and MCP quick start.
Server listing: smithery.ai/servers/samson-art/transcriptor-mcp
URL: https://server.smithery.ai/samson-art/transcriptor-mcp
Requires session apiToken (header token issued via Google Form)
Smithery maps session apiToken to upstream X-MCP-Api-Token. Keep the token secret (do not commit or log).
Full Smithery setup steps and examples are in How to connect.
Other directories and one-click listings:
Multi-platform — YouTube, Reddit, Twitter/X, Instagram, TikTok, Twitch, Vimeo, Facebook, Bilibili, VK, Dailymotion.
Connect by URL (Smithery, Glama) — use the server without installing Docker or Node; Smithery, Glama.
Transcripts + raw subtitles: cleaned text or raw SRT/VTT.
Language support: official subtitles with auto-generated fallback.
Video metadata: extended info (title, channel, tags, thumbnails, etc.) and chapter markers.
Pagination: safe for large transcripts.
Whisper fallback: when subtitles are unavailable, transcribes video audio via Whisper (local self-hosted or OpenAI API); configurable via environment variables.
Optional Redis cache: cache subtitles and metadata to reduce yt-dlp calls; configurable via environment variables.
Docker-first: ready for local + remote deployment.
Production-friendly HTTP: optional auth + allowlists for the REST API; remote MCP uses stdio + mcp-proxy and is usually fronted by your own reverse proxy for Bearer/TLS.
Prometheus: metrics on the REST API (GET /metrics); MCP tool counters (mcp_*) are updated inside the MCP Node process but this repo no longer exposes GET /metrics on the MCP image.
You can enable these features independently; both are off by default.
Whisper fallback — When native subtitles are unavailable, transcribe video audio via Whisper (local self-hosted or OpenAI API). Configure via WHISPER_MODE, WHISPER_BASE_URL, WHISPER_API_KEY, etc.
Redis caching — Cache subtitles and metadata to reduce yt-dlp calls. Configure via CACHE_MODE=redis and CACHE_REDIS_URL.
For full setup options (Local Docker, Smithery remote, and self-hosted HTTP/SSE with mcp-proxy), use:
Tool | Purpose |
| Cleaned plain text (first chunk) |
| Raw SRT/VTT, paginated |
| List official/auto languages |
| Extended metadata |
| Chapter markers |
| Batch transcripts from playlist |
| YouTube search |
All URL-based tools share the same base input:
url (string, required) – Video URL from a supported platform or YouTube video ID. Supported: YouTube, Twitter/X, Instagram, TikTok, Twitch, Vimeo, Facebook, Bilibili, VK, Dailymotion, Reddit.
get_raw_subtitles supports pagination; get_transcript returns the first chunk only (no pagination input). Pagination parameters for get_raw_subtitles:
response_limit (number, optional) – max characters per response, default 50000, min 1000, max 200000.
next_cursor (string, optional) – opaque offset returned from the previous page; pass it to fetch the next chunk.
Each tool returns:
content – human-readable text (for MCP chat UIs).
structuredContent – strongly typed JSON payload you can consume from automations or code.
get_transcriptPurpose: Fetch cleaned subtitles as plain text (no timestamps, HTML, or speaker metadata).
Input: Only url (video URL or ID). Type and language are auto-discovered; the tool returns the first chunk with default size (no pagination parameters).
Structured response:
videoId – resolved YouTube ID.
type, lang – effective subtitle type and language.
text – current text chunk.
is_truncated – true if more text is available.
total_length – total length of the full transcript.
start_offset, end_offset – character offsets of this chunk.
next_cursor – present in response when truncated (omitted on the last page). Not accepted as input for this tool.
get_raw_subtitlesPurpose: Fetch raw subtitle file content (SRT or VTT) with pagination support.
Extra input fields:
type – "official" or "auto", optional.
lang – subtitle language code, optional.
response_limit, next_cursor – pagination (optional).
Structured response:
videoId, type, lang – same semantics as above.
format – "srt" or "vtt" (auto-detected from content).
content – raw subtitle text for this page.
is_truncated, total_length, start_offset, end_offset, next_cursor – same pagination fields as get_transcript.
get_available_subtitlesPurpose: Inspect which languages are available for a video, split into official vs auto-generated tracks.
Input:
url – YouTube URL or video ID.
Structured response:
videoId – resolved YouTube ID.
official – sorted list of language codes with official subtitles.
auto – sorted list of language codes with auto-generated subtitles.
This is useful to first discover languages and then pick type/lang for get_raw_subtitles (or other tools).
get_video_infoPurpose: Fetch extended metadata about a video (based on yt-dlp JSON output).
Input:
url – YouTube URL or video ID.
Structured response (key fields):
videoId – resolved YouTube ID.
title, description.
uploader, uploaderId.
channel, channelId, channelUrl.
duration – in seconds.
uploadDate – YYYYMMDD string if available.
webpageUrl.
viewCount, likeCount, commentCount.
tags, categories.
liveStatus, isLive, wasLive, availability.
thumbnail – primary thumbnail URL.
thumbnails – list of thumbnail variants { url, width?, height?, id? }.
See src/mcp-core.ts and src/youtube.ts for the full JSON schema used by the MCP SDK.
get_video_chaptersPurpose: Get chapter markers extracted by yt-dlp.
Input:
url – YouTube URL or video ID.
Structured response:
videoId – resolved YouTube ID.
chapters – array of { startTime: number; endTime: number; title: string }.
If the video has no chapters, chapters is an empty array; if yt-dlp cannot fetch chapter data at all, the tool returns an MCP error instead of structured chapters.
get_playlist_transcriptsPurpose: Fetch cleaned transcripts for multiple videos from a playlist in one call.
Input:
url (string, required) – Playlist URL or watch URL with list= (e.g. https://www.youtube.com/playlist?list=XXX).
type – "official" or "auto", optional.
lang – Subtitle language code, optional.
format – Subtitle format (srt, vtt, ass, lrc), optional.
playlistItems – yt-dlp -I spec (e.g. 1:5, 1,3,7, -1), optional.
maxItems – Max videos to process, optional.
Structured response:
results – array of { videoId, text } for each video in the playlist.
search_videosPurpose: Search videos on YouTube via yt-dlp (ytsearch). Returns a list of videos with metadata.
Input:
query (string, required) – Search query.
limit (number, optional) – Max results (default 10, max 50).
offset (number, optional) – Skip first N results (pagination).
uploadDateFilter (string, optional) – Filter by upload date: hour, today, week, month, or year.
response_format (string, optional) – Human-readable format: json (default) or markdown.
Structured response:
results – array of { videoId, title, url, duration, uploader, viewCount, thumbnail }.
Docker (recommended for production)
Node.js >= 20.0.0 (for local development)
yt-dlp (included in Docker image)
The repository also ships an HTTP API (Fastify).
Build the image:
docker build -t transcriptor-mcp-api -f Dockerfile --target api .Run on the default port:
docker run -p 3000:3000 transcriptor-mcp-apiFor a more complete REST quick start (including docker-compose and local Node.js), use REST API (optional) and API Documentation.
Once the REST API is running, interactive API docs are available at:
http://localhost:3000/docsIf you change PORT / HOST, adjust the URL accordingly, e.g. http://<HOST>:<PORT>/docs.
If yt-dlp is blocked by age gate, sign-in, or region restrictions, you will likely need
an authenticated cookies.txt file and the COOKIES_FILE_PATH environment variable.
The root of this repository includes a sample [cookies.example.txt](cookies.example.txt)
showing the expected Netscape cookies format. For a full guide on:
exporting real cookies
wiring them into Docker / docker-compose / local Node.js
and keeping them secure
keep credentials local and use COOKIES_FILE_PATH with a non-committed cookie file.
docker run -d -p 3000:3000 --name transcriptor transcriptor-mcp-apiBefore publishing Docker images, you can run a small e2e smoke test that:
Starts a REST API container and checks Swagger + POST /subtitles with a stable YouTube video
Optionally starts an MCP container and checks MCP stdio (initialize over stdin/stdout), streamable HTTP (POST /mcp with initialize), and SSE (GET /sse) against mcp-proxy + stdio (same stack as docker-compose.example.yml)
Run the smoke test (requires built images):
npm run build
docker build -t artsamsonov/transcriptor-mcp-api:latest -f Dockerfile --target api .
docker build -t artsamsonov/transcriptor-mcp:latest -f Dockerfile --target mcp .
npm run test:e2e:apiEnvironment variables:
Variable | Default | Description |
| — | Full API image reference (overrides name/tag). |
|
| API image name and tag. |
|
| API base URL and port. |
|
| Video used for |
| — | Set to |
| — | Full MCP image reference (overrides name/tag). |
|
| MCP image name and tag. |
|
| MCP base URL and port. |
| — | If set, sent as |
Example: skip MCP and use a custom video:
SMOKE_SKIP_MCP=1 SMOKE_VIDEO_URL="https://www.youtube.com/watch?v=YOUR_ID" npm run test:e2e:apidocker logs -f transcriptordocker stop transcriptor
docker rm transcriptorFor detailed REST API endpoint documentation (request/response schemas, examples, etc.), use the built-in Swagger UI at:
http://localhost:3000/docsor use REST API (optional).
The MCP server runs on stdio (dist/mcp.js) and can be used via:
local Docker (docker run --rm -i artsamsonov/transcriptor-mcp:latest)
local Node (node dist/mcp.js)
remote HTTP/SSE through mcp-proxy (/mcp and /sse)
Use How to connect as the main guide for MCP setup variants and auth notes (apiToken/X-MCP-Api-Token for Smithery vs Bearer on your own edge).
The API receives a video URL (YouTube or other supported platform) and parameters (subtitle type and language) from the client
Extracts the video ID from the URL
Uses yt-dlp to download subtitles with the specified parameters:
Single yt-dlp command call with explicit type (--write-subs or --write-auto-subs) and language (--sub-lang)
Parses the subtitle file (SRT/VTT) and removes:
Timestamps
Subtitle numbers
HTML tags
Formatting
Returns clean plain text (for /subtitles) or raw content (for /subtitles/raw)
Node.js >= 20.0.0
npm or yarn
yt-dlp installed and available in PATH
The app version is read from package.json at runtime ([src/version.ts](src/version.ts)). When cutting a release, update the version field in package.json, then create a git tag (e.g. v0.4.7). Changelog entries under [Unreleased] should be moved to the new version before tagging.
npm run build - Build the TypeScript project
npm start - Run the compiled application
npm run dev - Run with hot reload using ts-node-dev
npm run start:mcp - Run the MCP server (stdio)
npm run dev:mcp - Run the MCP server with hot reload
npm test - Run tests
npm run test:watch - Run tests in watch mode
npm run test:coverage - Run tests with coverage report
npm run lint - Lint the code
npm run lint:fix - Fix linting errors
npm run type-check - Type check without building
npm run format - Format code with Prettier
npm run format:check - Check code formatting
├── src/
│ ├── index.ts # HTTP API (Fastify)
│ ├── mcp.ts # MCP server (stdio)
│ ├── mcp-core.ts # MCP tools registration
│ ├── validation.ts # Request validation
│ ├── youtube.ts # Subtitle download and parsing (yt-dlp)
│ ├── yt-dlp-check.ts # yt-dlp availability checks
│ ├── whisper.ts # Whisper API client
│ ├── whisper-jobs.ts # Async Whisper jobs
│ ├── cache.ts # Response / subtitle caching
│ ├── metrics.ts # Prometheus metrics (/metrics)
│ ├── lifecycle.ts # Graceful shutdown hooks
│ ├── instrument.ts # Sentry initialization
│ ├── logger-sentry-breadcrumbs.ts
│ ├── errors.ts # Error types and HTTP mapping
│ ├── env.ts # Environment configuration
│ ├── version.ts # App version (from package.json)
│ ├── changelog.ts # Changelog data for API
│ ├── e2e/ # API / MCP smoke tests (Docker)
│ │ ├── api-smoke.ts
│ │ ├── mcp-smoke.ts
│ │ ├── docker-utils.ts
│ │ └── smoke-env.ts
│ └── *.test.ts # Unit tests (Jest), co-located
├── dist/ # Compiled JavaScript (npm run build)
├── load/ # Load-test scripts (k6)
├── scripts/ # Maintenance scripts (e.g. generate-server-card.mjs)
├── .github/workflows/ # CI and Docker Hub publish
├── Dockerfile # API and MCP images (--target api|mcp)
├── docker-compose.example.yml # Example API + MCP stack
├── docker-compose.yml
├── package.json
├── tsconfig.json
├── eslint.config.mjs
├── jest.config.cjs
├── smithery.yaml
└── README.mdTypeScript - Type-safe JavaScript
Node.js - Runtime environment
Fastify - Fast and low overhead web framework
yt-dlp - YouTube content downloader
Docker - Containerization
Jest - Testing framework
ESLint - Code linting
Prettier - Code formatting
Data and keys: Video URLs are sent to yt-dlp for subtitle extraction. Keys and tokens are stored only in your environment; we never log or share them.
Do not commit or log sensitive values. Use environment variables or a secret manager (e.g. vault, cloud secrets) for:
**WHISPER_API_KEY** – required when using Whisper API; never log or expose in client responses.
**CACHE_REDIS_URL** – Redis connection string when CACHE_MODE=redis; may contain credentials.
MCP Bearer secrets – if you terminate auth at a reverse proxy in front of mcp-proxy, store tokens only in env/secrets on that edge.
**COOKIES_FILE_PATH** – path to cookies; ensure the file is not committed and has restricted permissions.
Use cookies.example.txt as a format template and keep real cookies outside git.
Contributions are welcome! Please feel free to submit a Pull Request.
Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request
Please make sure your code passes all tests and linting checks before submitting.
MIT License
Copyright (c) 2025 samson-art
See LICENSE file for details.
Bug reports: GitHub Issues
Feature requests: GitHub Issues
Contact: GitHub Profile
List available official and auto-generated subtitle languages.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Video URL (supported: YouTube, Twitter/X, Instagram, TikTok, Twitch, Vimeo, Facebook, Bilibili, VK, Dailymotion, Reddit) or YouTube video ID | |
| format | No | Subtitle format (default from YT_DLP_SUB_FORMAT or srt) |
| Name | Required | Description |
|---|---|---|
| auto | Yes | |
| videoId | Yes | |
| official | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is clear. The description adds that it lists both official and auto-generated languages, which is minor behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 8 words, concise and front-loaded with the action. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of annotations and output schema, the description is nearly complete. It covers the core purpose, though it could briefly hint at the return format (e.g., 'returns list of language codes').
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both parameters (url and format) described in detail. The description does not add any extra meaning beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List available official and auto-generated subtitle languages' clearly specifies the verb (List) and resource (subtitle languages), and distinguishes from sibling tools like get_raw_subtitles and get_transcript.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when or when not to use this tool, nor does it mention alternatives. It lacks explicit context for usage decisions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch cleaned subtitles (plain text) for multiple videos from a playlist. Use playlistItems (e.g. "1:5") to select specific items, maxItems to limit count.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Playlist URL (e.g. youtube.com/playlist?list=XXX) or watch URL with list= parameter | |
| lang | No | Language code (e.g. en, ru). Default: en | |
| type | No | Subtitle track type: official or auto-generated (default: auto) | |
| format | No | Subtitle format (default from YT_DLP_SUB_FORMAT or srt) | |
| maxItems | No | Max number of videos to fetch (yt-dlp --max-downloads) | |
| playlistItems | No | yt-dlp -I spec: "1:5", "1,3,7", "-1" for last, "1:10:2" for every 2nd |
| Name | Required | Description |
|---|---|---|
| results | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds value by specifying that subtitles are 'cleaned (plain text)', which is a behavioral trait not inferable from annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each serving a purpose: first describes the core function, second explains key parameter usage. No extraneous words. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters, 100% schema coverage, output schema exists, and annotations present, the description covers the core functionality and critical parameters. Minor gap: no mention of return format or error conditions, but output schema likely covers that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description goes beyond by providing concrete examples for playlistItems and maxItems ('1:5', '1,3,7'), adding meaning to those parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetch cleaned subtitles (plain text) for multiple videos from a playlist.' It uses a specific verb ('Fetch'), identifies the resource ('cleaned subtitles for multiple videos from a playlist'), and distinguishes from sibling get_transcript (single video) by specifying 'multiple'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage hints for playlistItems and maxItems (e.g., 'Use playlistItems (e.g. "1:5") to select specific items, maxItems to limit count.'), but does not explicitly contrast with siblings like get_transcript or get_raw_subtitles. However, the context of 'multiple videos from a playlist' implies the distinction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch raw SRT/VTT subtitles for a video (supported platforms). Optional: type, lang, response_limit (when omitted returns full content), next_cursor for pagination.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Video URL (supported: YouTube, Twitter/X, Instagram, TikTok, Twitch, Vimeo, Facebook, Bilibili, VK, Dailymotion, Reddit) or YouTube video ID | |
| lang | No | Language code (e.g. en, es). When omitted with Whisper fallback, language is auto-detected | |
| type | No | Subtitle track type: official or auto-generated | |
| format | No | Subtitle format (default from YT_DLP_SUB_FORMAT or srt) | |
| next_cursor | No | Opaque cursor from previous response for pagination | |
| response_limit | No | Max characters per response. When omitted, returns full content. When set: min 1000 |
| Name | Required | Description |
|---|---|---|
| lang | Yes | |
| type | Yes | |
| format | Yes | |
| source | No | |
| content | Yes | |
| videoId | Yes | |
| end_offset | Yes | |
| next_cursor | No | |
| is_truncated | Yes | |
| start_offset | Yes | |
| total_length | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint and idempotentHint true, confirming safe reads. The description adds valuable behavioral context: optional type/lang, response_limit behavior (full content when omitted), and pagination via next_cursor, which enhances transparency beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the core purpose and efficiently conveys key optional parameters and behaviors. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists (reducing need to explain returns), the description covers essential aspects: supported platforms, format handling, language/track type options, pagination, and response limit behavior. It is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining response_limit's omitted behavior (returns full content) and notes pagination cursor, providing context not in the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches raw SRT/VTT subtitles for a video, mentioning supported platforms and optional parameters. It distinguishes from siblings like get_available_subtitles (lists available tracks) and get_transcript (likely plain text).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly advise when to use this tool versus alternatives. It implies usage for raw subtitle fetching but lacks exclusions or contextual guidance for selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch cleaned subtitles as plain text for a video (YouTube, Twitter/X, Instagram, TikTok, Twitch, Vimeo, Facebook, Bilibili, VK, Dailymotion, Reddit). Uses auto-discovery for type/language when omitted. Optional: type, lang, response_limit (when omitted returns full transcript), next_cursor for pagination.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Video URL (supported: YouTube, Twitter/X, Instagram, TikTok, Twitch, Vimeo, Facebook, Bilibili, VK, Dailymotion, Reddit) or YouTube video ID | |
| lang | No | Language code (e.g. en, es). When omitted with Whisper fallback, language is auto-detected | |
| type | No | Subtitle track type: official or auto-generated | |
| format | No | Subtitle format (default from YT_DLP_SUB_FORMAT or srt) | |
| next_cursor | No | Opaque cursor from previous response for pagination | |
| response_limit | No | Max characters per response. When omitted, returns full content. When set: min 1000 |
| Name | Required | Description |
|---|---|---|
| lang | Yes | |
| text | Yes | |
| type | Yes | |
| source | No | |
| videoId | Yes | |
| end_offset | Yes | |
| next_cursor | No | |
| is_truncated | Yes | |
| start_offset | Yes | |
| total_length | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint as true. The description adds behavioral context like 'cleaned subtitles', auto-discovery, and pagination via next_cursor, going beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loading the main purpose and then listing optional parameters with their behavior. Every sentence adds value, and there is no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and rich annotations, the description adequately covers the tool's purpose, supported platforms, and parameter behavior. It could mention prerequisites like public access, but overall it is complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema describes all parameters. The description adds value by clarifying that omitting response_limit returns the full transcript and that type/lang are auto-discovered when omitted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it fetches cleaned subtitles as plain text for videos from a wide range of platforms. It distinguishes from siblings like get_available_subtitles and get_raw_subtitles.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool but does not explicitly state when or when not to use it compared to alternatives. It mentions auto-discovery for type/language, but lacks exclusions or comparisons with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch chapter markers (start/end time, title) for a video.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Video URL (supported: YouTube, Twitter/X, Instagram, TikTok, Twitch, Vimeo, Facebook, Bilibili, VK, Dailymotion, Reddit) or YouTube video ID | |
| format | No | Subtitle format (default from YT_DLP_SUB_FORMAT or srt) |
| Name | Required | Description |
|---|---|---|
| videoId | Yes | |
| chapters | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds minimal behavioral context beyond stating the action, but does not contradict annotations. A score of 3 is appropriate as it does not significantly enhance transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, focused sentence with no unnecessary words. The essential information is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with 2 parameters and an output schema, the description is mostly sufficient. However, it could mention the return format (array of chapters) to improve completeness, but it is not missing critical information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are documented. The description adds minor context ('start/end time, title') that hints at output fields, but does not substantially improve parameter understanding beyond the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Fetch' and the resource 'chapter markers', specifying what they contain (start/end time, title). This distinguishes it from sibling tools like get_transcript or get_video_info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. It merely states what the tool does.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Capture a single frame from a video at the given timestamp. Provide timecode ("01:23", "00:01:23.500") or seconds; defaults to the first frame. Optional: format (png|jpeg), width (max 1920), quality (jpeg, 2-31). Returns the image plus metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Video URL (supported: YouTube, Twitter/X, Instagram, TikTok, Twitch, Vimeo, Facebook, Bilibili, VK, Dailymotion, Reddit) or YouTube video ID | |
| width | No | Output image width in pixels (default: 1280, max: 1920). Never upscales. | |
| format | No | Image format (default: jpeg) | |
| quality | No | JPEG quality (ffmpeg -q:v): 2 (best) to 31 (worst). Default: 4. Ignored for png. | |
| seconds | No | Timestamp in seconds (alternative to timecode). Default: 0 (first frame) | |
| timecode | No | Timestamp as "MM:SS" or "HH:MM:SS(.mmm)", e.g. "01:23" or "00:01:23.500" |
| Name | Required | Description |
|---|---|---|
| width | Yes | |
| videoId | Yes | |
| mimeType | Yes | |
| sizeBytes | Yes | |
| timestamp | Yes | |
| timestampSeconds | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and idempotent. Description adds useful details like 'Never upscales', format defaults, quality range, and that it returns image plus metadata, going beyond schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences covering key points. Could be slightly more structured but no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With full schema coverage, annotations, and output schema, the description is sufficient. It mentions return value and constraints, though doesn't list output metadata fields (but output schema does).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description enhances with examples (timecode format), defaults (width 1280), and notes (ffmpeg -q:v, ignored for png), adding value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear action ('Capture a single frame') and resource ('from a video') with specific details (at given timestamp). Differentiates from siblings like get_video_info or get_transcript.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context on defaults (first frame) and optional parameters, but no explicit when-to-use or when-not-to-use compared to alternatives. Still clear enough for typical usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch extended metadata for a video (title, channel, duration, tags, thumbnails, etc.).
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Video URL (supported: YouTube, Twitter/X, Instagram, TikTok, Twitch, Vimeo, Facebook, Bilibili, VK, Dailymotion, Reddit) or YouTube video ID | |
| format | No | Subtitle format (default from YT_DLP_SUB_FORMAT or srt) |
| Name | Required | Description |
|---|---|---|
| tags | Yes | |
| title | Yes | |
| isLive | Yes | |
| channel | Yes | |
| videoId | Yes | |
| wasLive | Yes | |
| duration | Yes | |
| uploader | Yes | |
| channelId | Yes | |
| likeCount | Yes | |
| thumbnail | Yes | |
| viewCount | Yes | |
| categories | Yes | |
| channelUrl | Yes | |
| liveStatus | Yes | |
| thumbnails | Yes | |
| uploadDate | Yes | |
| uploaderId | Yes | |
| webpageUrl | Yes | |
| description | Yes | |
| availability | Yes | |
| commentCount | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only and idempotent. The description adds that it fetches extended metadata and lists examples, but does not disclose potential behaviors like error handling or supported URL format details beyond what is in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that effectively communicates the tool's purpose without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and the tool's straightforward nature (fetching metadata), the description adequately covers what the agent needs to know, including examples of metadata fields and supported platforms.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, but the description adds value by detailing supported platforms for the 'url' parameter and specifying default subtitle format for 'format'. This enriches agent understanding beyond the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches extended metadata for a video, listing examples like title, channel, duration, etc. This distinguishes it from siblings that focus on subtitles or chapters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like get_transcript or get_video_chapters. The description does not mention scenarios where this tool is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search videos on YouTube via yt-dlp (ytsearch). Returns list of matching videos with metadata. Optional: limit, offset (pagination), uploadDateFilter (hour|today|week|month|year), dateBefore, date, matchFilter (e.g. "!is_live"), response_format (json|markdown).
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | yt-dlp --date, exact date e.g. "20231215" or "today-2weeks" | |
| limit | No | Max results (default 10) | |
| query | No | Search query | |
| offset | No | Skip first N results (pagination) | |
| dateBefore | No | yt-dlp --datebefore, e.g. "now-1year" or "20241201" | |
| matchFilter | No | yt-dlp --match-filter, e.g. "!is_live" or "duration < 3600 & like_count > 100" | |
| response_format | No | Format of the human-readable content: json (default) or markdown | |
| uploadDateFilter | No | Filter by upload date (relative to now) |
| Name | Required | Description |
|---|---|---|
| results | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true. Description adds parameter details but lacks behavioral context like rate limits or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence front-loads purpose and lists key parameters with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With output schema present, return values are covered. Description explains parameters adequately, though pagination and edge cases could be clearer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%. Description adds value with examples (e.g., '!is_live' for matchFilter) and clarifies pagination, though not all parameters gain meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches videos on YouTube via yt-dlp and returns a list with metadata, distinguishing it from siblings like get_video_info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like get_video_info or get_transcript. Usage is implied but not detailed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.2.0get_video_frameEach tool has a clearly distinct purpose targeting specific aspects of video content processing: subtitles (available, raw, cleaned, playlist), chapters, metadata, and search. There is no overlap in functionality, with clear boundaries between subtitle retrieval methods and other operations.
All tools follow a consistent verb_noun pattern using snake_case (e.g., get_available_subtitles, search_videos). The naming is predictable and readable throughout the set, with no deviations in style or convention.
With 7 tools, the server is well-scoped for video transcription and metadata retrieval. Each tool earns its place by covering distinct operations like subtitle fetching, chapter extraction, info retrieval, and search, without being overly sparse or bloated.
The tool surface provides comprehensive coverage for video transcription and metadata, including CRUD-like operations for subtitles (list, get raw, get cleaned) and extended info. A minor gap exists in subtitle management (e.g., no update or delete tools), but agents can work around this as the focus is on retrieval.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
An MCP server that gives any LLM or agent clean YouTube transcripts on demand: a single video, a whole channel, or a playlist, plus AI cleanup of auto-generated captions. API-key auth, credit-based, same backend as the public v1 API. Get a free API key with 25 free credits at youtubetranscriptdownload.com/account.
MCP server for RiverScript, an AI transcription platform - fetches transcripts shared via a link.
MCP server for Clipkit — gives AI agents a video toolbox via the Clipkit schema.
An MCP server that provides congressional transcripts
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/samson-art/transcriptor-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
