Transcriptor MCP

Transcriptor MCP is an MCP server that retrieves video transcripts and subtitles via yt-dlp, with pagination for large results. It supports popular platforms such as YouTube, Twitter/X, Instagram, TikTok, Twitch, Vimeo, Facebook, Bilibili, VK, and Dailymotion, with a Whisper-based fallback to transcribe audio when subtitles are unavailable. It can run locally via stdio or remotely over HTTP/SSE and works with Cursor and other MCP hosts.

How to use

You can use Transcriptor MCP with any MCP client that supports stdio or HTTP/SSE. For local usage, run the MCP server in stdio mode and connect your client to its standard input and output. For remote usage, run the HTTP/SSE server on a VPS or similar host and connect your client via HTTP or SSE endpoints.

How to install

Prerequisites: ensure you have Docker installed on your machine. For development, you may also install Node.js 20+ and yt-dlp in environments that run the MCP server directly.

Additional sections

MCP server connections and deployment patterns: you can deploy the MCP server in two main ways. First, use Docker to run the stdio MCP server locally. Second, deploy the HTTP/SSE MCP server on a VPS and expose the API via Docker Compose. You will connect clients using either the stdio channel or the HTTP/SSE endpoints.

MCP quick start (examples)

To run the MCP server locally in stdio mode using Docker, use the following command.

docker run --rm -i artsamsonov/transcriptor-mcp:latest

Remote MCP over HTTP/SSE deployment

On your VPS, prepare a Docker Compose setup and start the HTTP/SSE MCP server. The default port is 4200.

cp docker-compose.example.yml docker-compose.yml
docker compose up -d transcriptor-mcp

Connecting clients to the remote server

Use the MCP URL to connect your client. For Claude, add an HTTP transport using the MCP URL shown below. For Cursor, configure an SSE transport with the sse URL.

Claude: mcp add --transport http transcriptor http://<tailscale-host>:4200/mcp
Cursor: add a new MCP server of type SSE with URL http://<tailscale-host>:4200/sse

Notes on authentication and headers

If you enable authentication for MCP HTTP, include an Authorization: Bearer < token > header in client requests. You can set MCP_AUTH_TOKEN to configure Bearer token usage.

MCP tools overview

Transcriptor MCP exposes a suite of tools to fetch and process transcripts and video metadata. The tools include: get_transcript, get_raw_subtitles, get_available_subtitles, get_video_info, and get_video_chapters. Each tool returns both a human-friendly content field and a structured payload for automation.

Security and cookies guidance

If yt-dlp access is restricted by age gates, sign-in, or regional blocks, you may need an authenticated cookies.txt file and the COOKIES_FILE_PATH environment variable. Keep cookies secure and do not commit them.

Monitoring and caching

Optional Redis caching can be enabled to cache subtitles and metadata to reduce yt-dlp calls. You can also enable Prometheus metrics to monitor API and MCP usage and failures.

Development and maintenance

Developers will use Node.js and TypeScript to build and run the project locally. The project provides commands to build, run, test, and lint. Versioning is tied to package.json, and releases are tagged accordingly.

Project notes and structure

The project includes an MCP server over stdio and an HTTP/SSE server, sharing the same yt-dlp-based extraction and parsing pipeline. Pagination is supported for large outputs, and the Whisper fallback provides coverage when official subtitles are unavailable.

Available tools

get_transcript

Fetch cleaned plain text subtitles for a video; returns first chunk by default with basic text content.

get_raw_subtitles

Fetch raw subtitle files (SRT/VTT) with pagination support.

get_available_subtitles

List languages available for a video, split into official and auto-generated tracks.

get_video_info

Fetch extended video metadata such as title, channel, tags, thumbnails, and more.

get_video_chapters

Retrieve chapter markers with start and end times and titles.