artsamsonov/transcriptor-mcp repository overview

⁠Transcriptor MCP

Now your AI assistant can watch videos.

Connect one server. Then ask Claude, ChatGPT, or Cursor about any video: the transcript, the chapters, the metadata, or a single frame. It works with 11 platforms, not only YouTube.

Website: https://transcriptor-mcp.org⁠ Source and full documentation: https://github.com/samson-art/transcriptor-mcp⁠ In the MCP Registry as io.github.samson-art/transcriptor-mcp.

⁠⚡ Start with the hosted server

You do not need this image to use the tools. A hosted server is ready:

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

Your client opens a browser and you sign in there. There is no API key to copy.

One click: Add to Cursor⁠ · Add to VS Code⁠ · Add to LM Studio⁠

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.

Claude (web and desktop): open Settings → Customize → Connectors. Select Add → Add custom connector, paste the URL, then select Add.

ChatGPT and Codex: install Transcriptor from the ChatGPT plugin directory⁠ — select Install plugin, sign in when asked, then mention @Transcriptor in a chat. Codex shares the directory: Sources → Use plugins → Transcriptor, or /plugins in the CLI.

Windsurf, Cline, Zed, Gemini CLI: each client wants a different config shape. The website⁠ has a ready snippet for every one of them.

Any other MCP client:

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

The hosted server is governed by the Terms of Service⁠ and the Privacy Policy⁠. A server you run from this image is governed by the MIT Licence alone.

⁠🐳 Use this image to run your own server

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

The image serves Streamable HTTP on port 4200:

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

Then point your client at http://<host>: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"]
    }
  }
}

With docker compose:

services:
  transcriptor-mcp:
    image: artsamsonov/transcriptor-mcp:latest
    ports:
      - "4200:4200"

The repository file docker-compose.example.yml shows a full stack with a Whisper service and COOKIES_FILE_PATH.

Transport. The server accepts POST /mcp only. GET and DELETE return 405. The server is stateless and sends no Mcp-Session-Id. The same port serves GET /health and GET /metrics in Prometheus format.

Authentication. 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 server works this way.

⁠🧰 Tools

All eight tools are read-only.

Four tools also have an interactive interface: get_transcript, get_video_info, get_video_frame, and search_videos. Clients that support MCP Apps or 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

The tool search_videos works with YouTube only. The server returns text, metadata and single still frames. It never returns video or audio files.

⁠🗣️ Whisper fallback

When a video has no subtitles, the server can transcribe the audio. Set WHISPER_MODE:

• local — a self-hosted Whisper service, for example whisper-asr-webservice⁠. Set WHISPER_BASE_URL.
• api — the OpenAI Whisper API, or a compatible one. Set WHISPER_API_KEY, and WHISPER_API_BASE_URL if the host is different.
• off — the default. No transcription.

The tools get_transcript and get_raw_subtitles report the origin in structuredContent as source: "youtube" or source: "whisper".

⁠⚙️ Environment variables

The image starts with no environment variables. Each variable below is optional; .env.example in the repository lists the rest.

If a video needs an account, mount your cookies file:

docker run --rm -p 4200:4200 \
  -e COOKIES_FILE_PATH=/cookies/cookies.txt \
  -v "/path/to/cookies.txt:/cookies/cookies.txt:ro" \
  artsamsonov/transcriptor-mcp:latest

⁠Related image

artsamsonov/transcriptor-mcp-api gives the same extraction as a REST API, with a Swagger interface at /docs.

⁠License

MIT