transcriptor-mcp

Each tool that takes a video accepts url. This is a link from a supported platform or a plain YouTube ID. Each tool returns content (text for the chat) and structuredContent (typed JSON for your code).

get_transcript

Clean plain text, without timestamps, HTML, or speaker names. The tool finds the type and the language for you.

Response: videoId, type, lang, text, is_truncated, total_length, start_offset, end_offset. When more text is available, the response also has next_cursor.

get_raw_subtitles

Raw SRT or VTT content, in parts.

Input:

• type — official or auto
• lang — a language code
• response_limit — default 50000, minimum 1000, maximum 200000
• next_cursor — the cursor of the previous response

Response: the fields of get_transcript, plus format (srt or vtt) and content.

get_available_subtitles

Response: official and auto. Each field is a sorted list of language codes. Use this tool first, then give type and lang to the tools above.

get_video_info

Extended metadata from yt-dlp:

• identity — videoId, title, description, webpageUrl
• author — uploader, uploaderId, channel, channelId, channelUrl
• numbers — duration, uploadDate, viewCount, likeCount, commentCount
• classification — tags, categories, liveStatus, isLive, wasLive, availability
• images — thumbnail and thumbnails

get_video_chapters

Response: chapters. Each item has startTime, endTime, and title. When the video has no chapters, the list is empty.

get_video_frame

Input:

• timecode — "MM:SS" or "HH:MM:SS.mmm"
• seconds — an alternative to timecode. Give one of the two, not both
• format — jpeg (default) or png
• width — default 1280, maximum 1920, never larger than the source
• quality — 2 to 31, for jpeg only

Response: an image block, plus timestampSeconds, timestamp, mimeType, sizeBytes, and width. This tool needs ffmpeg. The Docker image includes it.

get_playlist_transcripts

Input:

• url — a playlist URL, or a watch URL with list=
• type, lang, format — the same as get_raw_subtitles
• playlistItems — a yt-dlp -I value such as 1:5, 1,3,7, or -1
• maxItems — the maximum number of videos

Response: results. Each item has videoId and text.

search_videos

Input:

• query — the search text
• limit — default 10, maximum 50
• offset — the number of results to skip
• uploadDateFilter — hour, today, week, month, or year
• response_format — json (default) or markdown

Response: results. Each item has videoId, title, url, duration, uploader, viewCount, and thumbnail.

Transport. The server accepts POST /mcp only. GET and DELETE return 405. The server is stateless and sends no Mcp-Session-Id.

The Node process does not check bearer tokens. Put a reverse proxy or a gateway in front of it for authentication and TLS. The hosted endpoint works this way.

REST API. A second image gives the same extraction over plain HTTP:

docker run --rm -p 3000:3000 artsamsonov/transcriptor-mcp-api:latest

The Swagger interface is at http://localhost:3000/docs. For a full stack with the API and the MCP server, read docker-compose.example.yml.

Development.

npm ci
npm run build
npm run dev:mcp        # stdio, hot reload
npm run dev:mcp:http   # Streamable HTTP, hot reload
npm test

You need Node.js 20 or later, and yt-dlp in your PATH. Frame capture also needs ffmpeg. Other scripts: lint, type-check, format, test:coverage, test:e2e:api, and test:e2e:mcp.

Releases. The version comes from package.json at runtime, through src/version.ts. Change this version, move the [Unreleased] entries of the changelog into the new version, then push a v* tag. CI builds both images and publishes the MCP Registry entry from server.json.

Layout. src/mcp.ts (stdio entry), src/mcp-http.ts (Streamable HTTP), src/mcp-core.ts (tools, prompts, widgets), src/youtube.ts (yt-dlp), src/whisper.ts, src/cache.ts, src/index.ts (REST API), load/ (k6), and src/e2e/ (Docker smoke tests).