samson-art/transcriptor-mcp

24 stars 0 forks Quality 62 Trend 32

One MCP server that gives Claude, ChatGPT, Cursor and any other AI app transcripts, chapters, metadata and frames from YouTube and 10 more video platforms.

Overview

the transcript, the chapters, the metadata, or a single frame. It works with 11 platforms, not only YouTube. Then run /mcp and approve the sign-in in the browser. After this, claude mcp list shows ✔ Connected. If your client is not in the list above, add the server with this configuration: If you want to run the server yourself, read Self-host. The tools are the same and you need no account. Long transcripts come in parts. Each response gives a cursor for the next part, so no text is lost. Full tool reference (input and structured response) 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). Clean plain text, without timestamps, HTML, or speaker names. Without lang, the tool returns the track in the video's original language.

README

⚡ Connect in 30 seconds

The hosted endpoint is:

https://transcriptor.gateway.mcpal.io/mcp

🖱️ One click

⌨️ One command, for Claude Code

claude mcp add --transport http transcriptor https://transcriptor.gateway.mcpal.io/mcp

Then run /mcp and approve the sign-in in the browser. After this, claude mcp list shows ✔ Connected.

🧭 No terminal

Client	What to do
Claude (web and desktop)	Open Settings → Customize → Connectors. Select Add → Add custom connector, paste `https://transcriptor.gateway.mcpal.io/mcp`, then select Add.
ChatGPT	Open Transcriptor in the ChatGPT plugin directory and select Install plugin; sign in when asked. Or in ChatGPT open Plugins, search Transcriptor, select Install plugin. Then mention `@Transcriptor` in a chat.
Codex	Same directory, one install: ChatGPT and Codex share it. In a Codex task open Sources → Use plugins → Transcriptor; in the CLI, `/plugins`.

🧩 Any other MCP client

If your client is not in the list above, add the server with this configuration:

{
  "mcpServers": {
    "transcriptor": {
      "url": "https://transcriptor.gateway.mcpal.io/mcp"
    }
  }
}

If you want to run the server yourself, read Self-host. The tools are the same and you need no account.

🧰 What you can ask

Ask for this	Tool
“Summarize this video for me”	`get_transcript`
“Give me the subtitles as an SRT file”	`get_raw_subtitles`
“Is there a German track for this video?”	`get_available_subtitles`
“Who published this and how many views?”	`get_video_info`
“Go to the part about pricing”	`get_video_chapters`
“Show me the screen at 4:12”	`get_video_frame`
“Get English transcripts for the first 5 videos in this playlist”	`get_playlist_transcripts`
“Find recent videos about X”	`search_videos` (YouTube)

Long transcripts come in parts. Each response gives a cursor for the next part, so no text is lost.

📺 Widgets

Four tools have an interactive interface: get_transcript, get_video_info, get_video_frame, and search_videos. Clients that support MCP Apps and the ChatGPT Apps SDK show this interface in the chat. Other clients get the same data as text and JSON.

🌍 Platforms

YouTube · Twitter/X · Instagram · TikTok · Twitch · Vimeo · Facebook · Bilibili · VK · Dailymotion · Reddit

Each tool that takes a video accepts a link from these 11 platforms. The tool search_videos works with YouTube only, through yt-dlp ytsearch.

The server does not download video or audio files for you. It returns text, metadata, and single frames.

🐳 Self-host

The tools are the same as on the hosted endpoint. You need no account.

Run the server with Docker. The image serves Streamable HTTP on port 4200:

docker run --rm -p 4200:4200 artsamsonov/transcriptor-mcp:latest

Then point your client at http://localhost:4200/mcp.

For stdio, give the image an explicit command:

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

{
  "mcpServers": {
    "transcriptor": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "artsamsonov/transcriptor-mcp:latest", "npm", "run", "start:mcp"]
    }
  }
}

The server starts with no environment variables. Each variable below is optional.

Variable	Default	Function
`MCP_PORT` and `MCP_HOST`	`4200` and `0.0.0.0`	The HTTP listener
`COOKIES_FILE_PATH`	—	A Netscape cookies file for videos that need an account. See cookies.example.txt
`WHISPER_MODE`	`off`	Set `local` or `api` to transcribe the audio when a video has no subtitles. Then set `WHISPER_BASE_URL` or `WHISPER_API_KEY`. `WHISPER_MAX_DURATION_SECONDS` skips longer videos and live streams; a video whose length the platform does not report is measured with `ffprobe` after the audio download
`CACHE_MODE`	`off`	Set `redis` and `CACHE_REDIS_URL` to cache subtitles and metadata
`YT_DLP_MAX_CONCURRENCY`	`4`	How many yt-dlp/ffmpeg processes may run at once. `YT_DLP_MAX_QUEUE` (`8`) is how many calls may wait; beyond that a call is refused at once with “server busy”. A call peaks at ~40 MiB, so the cap bounds platform throttling and latency, not memory
`SUBTITLES_RATE_LIMIT_HOLD_MS`	`600000`	After a platform answers 429 to a subtitle download, the server stops asking that platform for subtitles for this long and answers `rate_limited` right away. Each repeat doubles the wait, up to an hour; a successful download clears it. Metadata is not held back
`CANARY_INTERVAL_MS`	`900000`	How often the HTTP server fetches one transcript to prove the path still works. `0` turns it off; `CANARY_URL` picks the video
`YT_DLP_*`	—	Timeouts, proxy, and JS runtimes. See .env.example

The same port serves GET /health and GET /metrics. The metrics are in Prometheus format and include the mcp_* counters.

🤝 Contributing

Pull requests are welcome. Read CONTRIBUTING.md first: it describes the cycle from issue to review, for people and for coding agents.

⚖️ Legal

The hosted endpoint at transcriptor.gateway.mcpal.io is governed by the Terms of Service and the Privacy Policy.

A server you host yourself is not covered by those documents. It is governed by the MIT License only.

📄 License

💬 Support

Issues · GitHub profile · LinkedIn

View this README on GitHub

Install

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

Configuration

{
  "mcpServers": {
    "transcriptor": {
      "url": "https://transcriptor.gateway.mcpal.io/mcp"
    }
  }
}